//! The public `Session` (`include/metasequoia/session.h`, core-session.md §4): an input session plus the nine-key session, with the routing rules between them. One host serialises calls to its session; distinct sessions may run concurrently.
//!
//! The setters the product only sets at construction (`switch_scheme`, `set_helpcode_schema`, `set_helpcode_enabled`, `set_wubi_mixed_pinyin`, `set_personal_context_enabled`) and `candidate_key` stay public because the golden scenarios drive them. Learning undo (`set_learning_undo_enabled`, `forget_recent_commits`) is dropped.
mod candidates;
mod caret_edit;
mod chain;
mod clock;
mod commit;
mod composition;
mod conversion;
mod editing;
mod glide;
mod helpcode_entry;
mod input;
mod learning;
mod literal;
mod online;
pub mod options;
mod plugin_commands;
mod prediction;
mod raw_commit;
#[cfg(test)]
mod tests;
use std::path::PathBuf;
use std::sync::Arc;
use crate::diagnostics;
use crate::error::{EngineError, Result};
use crate::local::database::LocalDatabaseLease;
use crate::nine_key::{KeyGrid, NineKeySession};
use crate::pinyin::glide::{GlideKeyboard, GlidePoint};
use crate::touch::{KeyGeometry, KeyTouch, TouchTuning};
use crate::types::{
CandidateEdge, CandidateSource, Command, CommandTableEntry, CommandTranslationQuery,
FrequencyAdjustmentOptions, KeyResult, LocalInputMode, MentionEntry, OnlineQuery,
PluginCommand, PluginCommandQuery, QuickPhraseEntry, SchemeType, WordItem,
};
use crate::user_dictionary::journal::{release_thread_journal, JournalUse};
use crate::user_dictionary::ngram_store::{flush_journal, note_settled};
use crate::types::FirstPageRows;
pub use clock::{Clock, LocalClock};
use input::InputSession;
pub use options::{SessionOptions, SessionSnapshot};
pub struct Session {
input: InputSession,
nine_key: NineKeySession,
/// 触屏的组码网格：九键的数字从 `character` 进来，14 键的字母从 `grid_key` 进来；`None` 是不用网格。
key_grid: Option<KeyGrid>,
shuangpin_preedit_uses_raw: bool,
/// `SessionOptions::learn_typed_spellings_on_enter`。
learn_typed_spellings_on_enter: bool,
prediction: prediction::Prediction,
/// See [`Self::candidate_revision`].
revision: u64,
/// `msime_user.db` of this session's paths, written once more as the session ends.
journal: PathBuf,
journal_use: JournalUse,
/// The generation and resource directories the local-mode queries read; dropped after the rest of the session, so the last session to go closes their cached connections.
_local_databases: LocalDatabaseLease,
}
// A session may move to another thread between calls (a host's worker pool, the C ABI); calls into one session are still serialised by its owner, so it does not need to be `Sync`. The journal connections it opens are cached per thread, and its end closes the idle ones on every thread (`JournalUse`), so a session used on several threads leaves none open.
const _: fn() = || {
fn moves_between_threads<T: Send>() {}
moves_between_threads::<Session>();
};
impl Session {
/// Validates the paths and every option (`INVALID_SESSION_OPTIONS`, `UNKNOWN_HELPCODE_SCHEMA`), loads the helpcode table and applies the options in the reference order (session.cpp:11-30, 57-66).
pub fn new(options: SessionOptions) -> Result<Session> {
options.paths.validate()?;
crate::user_dictionary::generation::check_read_only_layout(&options.paths)?;
let input = InputSession::new(&options)?;
let mut nine_key = NineKeySession::new(
&options.paths,
options.learning,
options.frequency,
options.fuzzy_pinyin,
options.english,
options.enabled_schemes.contains(SchemeType::Quanpin),
options.single_character_only,
);
nine_key.set_stroke_dictionary(options.stroke_dictionary.clone());
nine_key.set_mixed_expressive(options.expressive);
nine_key.set_mixed_candidates_enabled(options.mixed_candidates);
nine_key.set_inline_date_time(
options
.local_modes
.date_time_inline
.then(|| Arc::clone(&input.clock.local)),
);
// 九键的整句与 26 键遵守同一组句子联想设置（#6059）。
nine_key.set_sentence_options(
options.sentence_association.clone(),
options.sentence_alternatives,
);
nine_key.set_first_page_rows(FirstPageRows::new(options.first_page_rows));
nine_key.set_rescoring_context(&options.rescoring_context);
// 九键选中的词记进同一个个人上下文模型，开关与 26 键相同（#6185）。
nine_key.set_personal_context_enabled(options.personal_context);
let journal = options.paths.user(crate::assets::USER_JOURNAL);
Ok(Session {
input,
nine_key,
key_grid: None,
shuangpin_preedit_uses_raw: options.shuangpin_preedit_uses_raw,
learn_typed_spellings_on_enter: options.learn_typed_spellings_on_enter,
prediction: prediction::Prediction::new(
options.next_word_prediction,
options.paths.dictionary(crate::assets::MAIN_DICTIONARY),
),
revision: 0,
journal_use: JournalUse::new(journal.clone()),
journal,
_local_databases: LocalDatabaseLease::new([
options.paths.dictionaries.clone(),
options.paths.resources.clone(),
]),
})
}
/// Changes whenever a call may have changed the candidate list, so a host that read the candidates under one revision can tell that an index it holds no longer means the same row. Read-only calls never change it; neither do the setters that only affect later keys (clock, key touch and geometry, touch tuning, punctuation options, rescoring context). Starts at 0 and only grows.
pub fn candidate_revision(&self) -> u64 {
self.revision
}
fn candidates_may_change(&mut self) {
self.revision = self.revision.wrapping_add(1);
}
/// 会话建立时定下的双拼方案（内置的表，或校验过的用户表）。
pub(crate) fn shuangpin_layout(&self) -> &'static crate::shuangpin::ShuangpinProfile {
self.input.profile
}
/// 会话现在过滤候选用的辅助码表（`SessionOptions::helpcode_table`、按 `helpcode_schema` 读的表，或之后 `set_helpcode_table` 换上的表）；辅助码关着时照样留着。门面给自己合成的整句补注释时读它，不另读一份。
pub(crate) fn helpcode_table(&self) -> Option<&crate::helpcode::HelpcodeKeymap> {
self.input.helpcode_keymap.as_deref()
}
/// Replace the steady and local clocks, so tests can cross the 3 s / 8 s / 10 s personal-learning windows and the date/time mode can be pinned.
pub fn set_clock(&mut self, clock: Clock) {
if self.input.local_mode_options.date_time_inline {
self.nine_key
.set_inline_date_time(Some(Arc::clone(&clock.local)));
}
self.input.clock = clock;
}
/// One ASCII character; `shift_only` is a bare Shift+letter (local mode entry). 全拼下九键开启且没有别的组字时，数字 2-9 交给九宫格会话；九键双拼交的是方案用到的数字（可以有 1 和 0）；注音九键的数字由注音编辑器自己处理。待用的触点（[`Self::set_key_touch`]）只交给 26 键组字，九宫格的数字用不到它，一律在这一键后作废。
pub fn character(&mut self, value: u8, shift_only: bool) -> KeyResult {
self.candidates_may_change();
self.prediction.clear();
let touch = self.input.pending_touch.take();
// English is a mode rather than a scheme, so the grid stays available in it: the same digits spell words instead of syllables. A local mode still takes the keys, and the scheme underneath must be quanpin: 拼音九宫格只认得全拼音节，注音九键走注音编辑器。九键双拼没有英文九键，专用英文里数字照常是数字。
let grid_digit = match self.key_grid {
Some(KeyGrid::NineKey) => (b'2'..=b'9').contains(&value),
Some(grid @ KeyGrid::NineKeyShuangpin(_)) => {
!self.input.dedicated_english && grid.is_code(value)
}
_ => false,
};
if grid_digit
&& self.input.scheme() == SchemeType::Quanpin
&& self.input.local_mode == LocalInputMode::None
&& self.input.preedit().is_empty()
{
let result = self.nine_key.character(value);
return self.after_nine_key(result);
}
if self.nine_key.active() {
// `'` splits the grid's syllables where the user is typing; any other key is still the host's to handle.
if value == b'\'' {
let result = self.nine_key.character(value);
return self.after_nine_key(result);
}
return KeyResult::unhandled();
}
self.input.pending_touch = touch;
self.input.handle_character(value, shift_only)
}
/// 下一次 `character` 的按下点（触屏宿主经 `msime_client_touch_character` 送来）。只有那一键是 26 键双拼的小写字母或 `;` 时才交给方案；其余会改动组字或改道按键的入口（命令、选词、以词定字、结束组字、钉住和删除候选、移光标、九宫格、网格键、滑行、标点、换方案、换网格或几何、展开首字母候选、重置上下文）一开头就丢掉它，所以改道到别处的按键不会把触点留给后面的字母。只改配置的 setter（辅助码表、云候选开关、重排上下文等）不碰它。
pub fn set_key_touch(&mut self, touch: Option<KeyTouch>) {
self.input.pending_touch = touch;
}
/// 宿主注册或清除的键位几何，见 [`crate::touch::KeyGeometry`]。
pub fn set_key_geometry(&mut self, geometry: Option<Arc<KeyGeometry>>) {
// 待用触点是按旧几何量出来的，交给新几何解释没有意义。
self.input.pending_touch = None;
self.input.engine.set_key_geometry(geometry);
}
/// 按触点计价的参数；只有 Rust 侧（评测示例）调用，不经 FFI。
pub fn set_touch_tuning(&mut self, tuning: TouchTuning) {
self.input.engine.set_touch_tuning(tuning);
}
/// 滑过字母键的一笔：它最可能拼出的全拼字母写到光标处，与已有组字之间用 `'` 隔开。不是全拼、在本地模式或专用英文里、九键数字正在组字，以及没有串跟得上这一笔时，不处理。
pub fn glide(&mut self, keyboard: &GlideKeyboard, points: &[GlidePoint]) -> KeyResult {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
if self.nine_key.active() {
return KeyResult::unhandled();
}
self.input.glide(keyboard, points)
}
/// 上一次 [`Session::set_key_grid`]（或 [`Session::set_nine_key_enabled`]）设下的组码网格，`None` 是不用网格；新会话是 `None`。网格开着时硬件键盘的字母照样走 26 键，要知道这次组字是不是在网格里打的，看 [`Session::grid_composing`]。
pub fn key_grid(&self) -> Option<KeyGrid> {
self.key_grid
}
/// 字母网格正在组字：九宫格会话（九键、14 键、18 键）在组字，快照、命令和上屏都来自它；或者五笔 14 键在组字，组码不是确定的字母。两种情况下的原样上屏都不是用户逐个打出的字母。
pub fn grid_composing(&self) -> bool {
self.nine_key.active() || self.input.wubi_grid_composing()
}
/// `set_key_grid` 的九键开关：开是九键，关是不用网格。
pub fn set_nine_key_enabled(&mut self, enabled: bool) {
self.set_key_grid(enabled.then_some(KeyGrid::NineKey));
}
/// 换触屏的组码网格，先丢掉网格里的组字，所以在换键盘布局、没有组字时调用。英文九键和注音九键只在九键下打开（注音组字会被丢掉）：14 键的英文模式画全键盘，注音没有 14 键。
pub fn set_key_grid(&mut self, grid: Option<KeyGrid>) {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
self.input.helpcode_entry = None;
self.nine_key.command(Command::Cancel);
if let Some(grid) = grid {
self.nine_key.set_grid(grid);
}
self.key_grid = grid;
let nine_key = grid == Some(KeyGrid::NineKey);
self.nine_key
.set_english_only(nine_key && self.input.dedicated_english);
self.input.set_zhuyin_nine_key(nine_key);
}
/// 字母网格的一键：小写字母由 `KeyGrid::code_of` 归成整组，十八键双拼另收大写 ASCII 标记精确字母。标记保留在组码里，不复用硬件键盘的 `character`。全拼和双拼分别使用自己的分组表，五笔在 14 键下按组展开码表（`wubi::grid`）；本地模式、专用英文或已有 26 键组字时不处理，状态不变。
pub fn grid_key(&mut self, letter: u8) -> KeyResult {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
let Some(
grid @ (KeyGrid::FourteenKey
| KeyGrid::EighteenKey
| KeyGrid::FourteenKeyShuangpin(_)
| KeyGrid::EighteenKeyShuangpin(_)),
) = self.key_grid
else {
return KeyResult::unhandled();
};
let Some(code) = grid.code_of(letter) else {
return KeyResult::unhandled();
};
// 五笔 14 键：键面与全拼 14 键相同，组码交给五笔方案按码表展开，不经九宫格会话。
if grid == KeyGrid::FourteenKey && self.input.scheme() == SchemeType::Wubi {
let Some(representative) = crate::wubi::grid::representative(code) else {
return KeyResult::unhandled();
};
return self.input.handle_wubi_grid_key(representative);
}
let supported = match grid {
KeyGrid::FourteenKey | KeyGrid::EighteenKey => {
self.input.scheme() == SchemeType::Quanpin
}
KeyGrid::FourteenKeyShuangpin(_) | KeyGrid::EighteenKeyShuangpin(_) => {
self.input.scheme() == SchemeType::Shuangpin
}
_ => false,
};
if !supported
|| self.input.local_mode != LocalInputMode::None
|| self.input.dedicated_english
|| !(self.input.preedit().is_empty() || self.nine_key.active())
{
return KeyResult::unhandled();
}
let result = self.nine_key.character(code);
self.after_nine_key(result)
}
/// 九宫格组码已经到上限时，这一键能不能先选掉首选、再接着打（`NineKeySession::limit_pick_ready`）。`grid_key` 为真时 `value` 是 `grid_key` 收到的归组字母，否则是 `character` 收到的九键或九键双拼数字；两条路由各自只认自己的网格。
pub fn grid_limit_pick_ready(&self, value: u8, grid_key: bool) -> bool {
let code = match self.key_grid {
Some(
grid @ (KeyGrid::FourteenKey
| KeyGrid::EighteenKey
| KeyGrid::FourteenKeyShuangpin(_)
| KeyGrid::EighteenKeyShuangpin(_)),
) if grid_key => grid.code_of(value),
Some(KeyGrid::NineKey | KeyGrid::NineKeyShuangpin(_)) if !grid_key => Some(value),
_ => None,
};
code.is_some_and(|code| self.nine_key.limit_pick_ready(code))
}
/// 九宫格会话活跃时选它的拼写；否则在注音里钉目标音节的读音。
pub fn choose_nine_key_spelling(&mut self, index: usize) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.nine_key.active() && self.input.zhuyin_rules_apply() {
return self.input.choose_zhuyin_spelling(index);
}
let result = self.nine_key.choose_spelling(index);
self.after_nine_key(result)
}
/// 九宫格组字时按单字、按笔画筛选候选（`NineKeySession::set_filter`）；没有九宫格组字时不处理。
pub fn set_nine_key_filter(&mut self, single_character: bool, strokes: &str) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.nine_key.active() {
return KeyResult::unhandled();
}
self.nine_key.set_filter(single_character, strokes)
}
/// 一条编辑命令。`CommitRaw` 原样上屏，专用英文里打的词学进英文词库（`SessionOptions::learn_english_on_enter`），`learn_typed_spellings_on_enter` 打开时还学临时模式与拼不成音节的拼音；`CommitRawWithoutLearning` 原样上屏、不学英文词。规则见 `session/raw_commit.rs`。
pub fn command(&mut self, command: Command) -> KeyResult {
match command {
Command::CommitRawWithoutLearning => self.commit_raw_without_learning(),
Command::CommitRaw if self.learn_typed_spellings_on_enter => {
self.commit_raw_learning_typed_spellings()
}
_ => self.dispatch_command(command),
}
}
/// 命令交给九宫格或组字，没有回车学词的策略。`CommitRawWithoutLearning` 不会到这里。
fn dispatch_command(&mut self, command: Command) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.prediction.rows.is_empty() {
self.prediction.clear();
return if command == Command::Cancel {
KeyResult::handled()
} else {
self.input.handle_command(command)
};
}
let selected = (self.prediction.enabled && command == Command::CommitCandidate)
.then(|| self.snapshot().candidates.first().cloned())
.flatten();
if self.nine_key.active() {
// 九宫格没有整句改字，改字的光标键就是它的光标键。
let command = match command {
Command::ConversionLeft => Command::MoveLeft,
Command::ConversionRight => Command::MoveRight,
other => other,
};
let result = self.nine_key.command(command);
let result = self.after_nine_key(result);
self.predict_after_commit(selected, &result);
return result;
}
let result = self.input.handle_command(command);
self.predict_after_commit(selected, &result);
result
}
/// 整句改字的左移，进入改字时从第 `index` 个候选（宿主高亮的那一行）开始；已在改字里时与 `command(ConversionLeft)` 相同。九宫格和进不了改字时按 `MoveLeft` 处理。
pub fn conversion_left_from(&mut self, index: usize) -> KeyResult {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
if self.nine_key.active() {
return self.command(Command::MoveLeft);
}
self.input.conversion_left_from(index)
}
/// `1`..`9` 选择组字候选；空闲联想不接管数字键。
pub fn candidate_key(&mut self, value: u8) -> KeyResult {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
if self.nine_key.active() {
if !(b'1'..=b'9').contains(&value) {
return KeyResult::unhandled();
}
let result = self.nine_key.select(usize::from(value - b'1'));
return self.after_nine_key(result);
}
self.input.handle_candidate_key(value)
}
/// Finishes the composition and appends the Chinese mark; unhandled when Chinese punctuation is off or locked to ASCII, or the key has no mark.
pub fn punctuation(&mut self, value: u8) -> KeyResult {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
if !self.nine_key.active() {
return self.input.handle_punctuation(value);
}
let mut result = self.input.handle_punctuation(value);
if !result.handled {
return result;
}
// The grid's text goes before the mark the input session translated.
let composition = self.nine_key.finish(0);
if composition.commit.is_some() {
self.input.reset_commit_context();
}
let mut text = composition.commit.unwrap_or_default();
text.push_str(result.commit.as_deref().unwrap_or_default());
result.commit = Some(text);
result
}
/// Live; keeps the composition, caret and pairing state.
pub fn set_chinese_punctuation_enabled(&mut self, enabled: bool) {
self.input.chinese_punctuation_enabled = enabled;
}
/// `INVALID_PUNCTUATION_LOCK` outside 0..=2.
pub fn set_punctuation_lock(&mut self, lock: i32) -> Result<()> {
if !(0..=2).contains(&lock) {
return Err(EngineError::invalid(diagnostics::INVALID_PUNCTUATION_LOCK));
}
self.input.punctuation_lock = lock;
Ok(())
}
pub fn set_paired_punctuation_enabled(&mut self, enabled: bool) {
self.input.punctuation.set_paired_enabled(enabled);
}
/// 换引号和方头括号的样式；组字、光标和交替状态都不动。
pub fn set_punctuation_marks(&mut self, marks: crate::punctuation::PunctuationMarks) {
self.input.punctuation.set_marks(marks);
}
/// The host emitted the closing half of a paired mark itself.
pub fn balance_paired_punctuation_after_auto_close(&mut self, opening: u8) {
self.input.punctuation.balance_after_auto_close(opening);
}
pub fn select(&mut self, index: usize) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.prediction.rows.is_empty() {
let Some((row, word, pinyin)) = self.prediction.selected(index) else {
return KeyResult::unhandled();
};
let diagnostic = self.input.record_personal_context(Some(&row), false, false);
self.show_prediction(&word, &pinyin, &row.word);
return KeyResult::committed(row.word.to_string()).with_diagnostic(diagnostic);
}
let selected = self
.prediction
.enabled
.then(|| self.snapshot().candidates.get(index).cloned())
.flatten();
if self.nine_key.active() {
let result = self.nine_key.select(index);
let result = self.after_nine_key(result);
self.predict_after_commit(selected, &result);
return result;
}
let result = self.input.select_candidate(index);
self.predict_after_commit(selected, &result);
result
}
/// Commit the first or last Han character of a candidate and drop the rest of the composition.
pub fn select_edge(&mut self, index: usize, edge: CandidateEdge) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.prediction.rows.is_empty() {
return KeyResult::unhandled();
}
if self.nine_key.active() {
return KeyResult::unhandled();
}
self.input.select_candidate_edge(index, edge)
}
/// Promote a dictionary candidate without committing; unsupported rows are unhandled, persistence failures carry a diagnostic.
pub fn pin(&mut self, index: usize) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.prediction.rows.is_empty() {
return KeyResult::unhandled();
}
if self.nine_key.active() {
return self.nine_key.pin(index);
}
self.input.pin_candidate(index)
}
/// Remove a dictionary phrase without committing; single-character non-English rows are protected.
pub fn remove(&mut self, index: usize) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.prediction.rows.is_empty() {
return KeyResult::unhandled();
}
if self.nine_key.active() {
return self.nine_key.remove(index);
}
self.input.remove_candidate(index)
}
/// Fix a dictionary candidate to slot 1..=5 in this input context; unhandled for any other slot.
pub fn fix_position(&mut self, index: usize, position: i32) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.prediction.rows.is_empty() {
return KeyResult::unhandled();
}
if !(1..=5).contains(&position) {
return KeyResult::unhandled();
}
if self.nine_key.active() {
return self.nine_key.set_position(index, position);
}
self.input.set_candidate_position(index, position)
}
pub fn clear_position(&mut self, index: usize) -> KeyResult {
self.candidates_may_change();
self.input.pending_touch = None;
if !self.prediction.rows.is_empty() {
return KeyResult::unhandled();
}
if self.nine_key.active() {
return self.nine_key.set_position(index, 0);
}
self.input.set_candidate_position(index, 0)
}
/// 从宿主高亮的候选开始结束整段组字（没有高亮时为 0），剩余片段使用各自首选；索引无效时提交原文。普通拼音中的大写片段由字面候选保留。
pub fn finish(&mut self, first_index: usize) -> KeyResult {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
if self.nine_key.active() {
let result = self.nine_key.finish(first_index);
return self.after_nine_key(result);
}
self.input.finish_composition(first_index)
}
/// Discards the composition. Fails, staying in the current scheme with the composition untouched, when the new scheme's dictionary cannot be opened (Cantonese without a usable `msime-cantonese.db`, Stroke without a usable `msime-stroke.db`: `LANGUAGE_DICTIONARY_UNAVAILABLE`, `LANGUAGE_DICTIONARY_VERSION_UNSUPPORTED`).
pub fn switch_scheme(&mut self, scheme: SchemeType) -> Result<()> {
self.candidates_may_change();
self.input.pending_touch = None;
self.input.switch_scheme(scheme)?;
self.prediction.clear();
self.nine_key.command(Command::Cancel);
Ok(())
}
pub fn is_supported_helpcode_schema(schema: &str) -> bool {
crate::helpcode::is_supported_helpcode_schema(schema)
}
/// False for an unsupported schema or a table that cannot be loaded.
pub fn set_helpcode_schema(&mut self, schema: &str) -> bool {
self.candidates_may_change();
self.input.set_helpcode_schema(schema)
}
/// 换上宿主给的辅助码表，替换当前的表；全拼和双拼都用它。
pub fn set_helpcode_table(&mut self, table: crate::helpcode::SharedKeymap) {
self.candidates_may_change();
self.input.set_helpcode_table(table);
}
/// Quanpin and shuangpin together, as `SessionOptions::helpcode` does.
pub fn set_helpcode_enabled(&mut self, enabled: bool) {
self.candidates_may_change();
self.input.set_helpcode_enabled(enabled);
}
/// 只有模式改变时才取消组字；重复设置保留当前输入。
pub fn set_dedicated_english(&mut self, enabled: bool) {
self.candidates_may_change();
self.input.pending_touch = None;
if self.input.dedicated_english == enabled {
return;
}
self.prediction.clear();
self.nine_key.command(Command::Cancel);
self.input.set_dedicated_english_mode(enabled);
// 九键在英文里用数字拼单词，在中文里拼音节，模式或网格改变时都要同步。
self.nine_key
.set_english_only(self.key_grid == Some(KeyGrid::NineKey) && enabled);
}
/// 混输候选的读音能继续时，运行时应保留组字，不提前顶字上屏。
pub fn wubi_pinyin_continues(&self, value: u8, shift: bool) -> bool {
!shift
&& !self.input.dedicated_english
&& self.input.local_mode == LocalInputMode::None
&& self.input.engine.wubi_pinyin_continues(value)
}
pub fn set_wubi_mixed_pinyin(&mut self, enabled: bool) {
self.candidates_may_change();
self.input.set_wubi_mixed_pinyin(enabled);
}
/// 五笔拼音混输是否打开。
pub fn wubi_mixed_pinyin(&self) -> bool {
self.input.engine.wubi_input_options().mixed_pinyin
}
/// 宿主的清缓存动作（维护快捷键、iOS 键盘扩展的内存告警）：清掉本会话各方案的候选缓存，并放掉进程级缓存里的日文模型和没有会话在用的个人学习模型，让不再用它们的进程能交还内存；本会话若正持有模型，照常用到会话结束。
pub fn reset_cache(&mut self) {
self.candidates_may_change();
self.prediction.clear();
self.input.reset_cache();
crate::japanese::decoder::JapaneseDictionary::release_shared();
crate::release_idle_personal_models();
}
/// Replace the `/` mode's command table; rows it cannot use are dropped. A diagnostic only if the open command list could not be refreshed.
pub fn set_command_table(&mut self, table: &[CommandTableEntry]) -> Option<String> {
self.candidates_may_change();
self.input.set_command_table(table)
}
/// 替换脚本插件的 `/` 指令；用不了的被丢弃（`local::command::usable_plugin_commands`），缓存的插件行清掉。只有打开的 `/` 列表刷新失败时才返回诊断。
pub fn set_plugin_commands(&mut self, commands: &[PluginCommand]) -> Option<String> {
self.candidates_may_change();
self.input.set_plugin_commands(commands)
}
/// 生效的插件指令里 `trigger` 的标题，见 `CandidateQueries::plugin_command_title`。
pub fn plugin_command_title(&self, trigger: &str) -> Option<&str> {
self.input.queries.plugin_command_title(trigger)
}
/// 替换 K 模式的宿主短语表；用不了的行被丢弃。只有打开的 K 模式列表刷新失败时才返回诊断。
pub fn set_quick_phrase_table(&mut self, table: &[QuickPhraseEntry]) -> Option<String> {
self.candidates_may_change();
self.input.set_quick_phrase_table(table)
}
/// Replace the `@` mode's list; entries it cannot use are dropped.
pub fn set_mention_entries(&mut self, entries: &[MentionEntry]) -> Option<String> {
self.candidates_may_change();
self.input.set_mention_entries(entries)
}
/// Turn the embedded places of `@` mode on or off.
pub fn set_mention_places(&mut self, enabled: bool) -> Option<String> {
self.candidates_may_change();
self.input.set_mention_places(enabled)
}
/// Forget the committed-word context (focus or application change, host-inserted text).
pub fn reset_context(&mut self) {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
self.input.reset_commit_context();
}
/// 宿主的即时隐私门禁；关闭时清掉建议，用户偏好仍保留。
pub fn set_prediction_allowed(&mut self, allowed: bool) {
self.candidates_may_change();
self.prediction.set_allowed(allowed);
}
/// Disabling also ends the current context.
pub fn set_personal_context_enabled(&mut self, enabled: bool) {
self.candidates_may_change();
self.prediction.clear();
self.input.set_personal_context_enabled(enabled);
self.nine_key.set_personal_context_enabled(enabled);
}
/// 当前组字是否预留云候选席位；运行时在修改前据此判断候选身份是否会变化。
pub fn cloud_candidates_enabled(&self) -> bool {
self.input.cloud_candidates_enabled
}
/// 让宿主把云候选的固定席位交给当前会话；关闭时立即去掉尚未回答的占位行。
pub fn set_cloud_candidates_enabled(&mut self, enabled: bool) {
self.candidates_may_change();
self.input.set_cloud_candidates_enabled(enabled);
}
pub fn english_online_candidates_enabled(&self) -> bool {
self.input.english_online_candidates_enabled
}
pub fn set_english_online_candidates_enabled(&mut self, enabled: bool) {
self.candidates_may_change();
self.input.set_english_online_candidates_enabled(enabled);
}
/// The committed text the neural sentence models condition on, updated without rebuilding the session. Only the last 64 characters matter.
pub fn set_rescoring_context(&mut self, context: &str) {
self.input.set_rescoring_context(context);
self.nine_key.set_rescoring_context(context);
}
/// 首页行数只决定词库要不要并入补全词。`Runtime` 建立、换引擎和宿主改每页候选数（`Runtime::set_page_size`）时都调它，因此引擎的首屏门槛和分页始终同源，不必等下一次因别的偏好变化重建引擎。
pub fn set_first_page_rows(&mut self, rows: FirstPageRows) {
self.candidates_may_change();
self.input.set_first_page_rows(rows);
self.nine_key.set_first_page_rows(rows);
}
/// 调频方式（`SessionOptions::frequency`），不重建会话就换掉；26 键和九宫格一起换。从下一次选择起按新方式学，已经学下的排序照旧生效，眼前的候选不重排。`trigger_count` 或 `linear_step` 不在 1..=10 时是 `INVALID_SESSION_OPTIONS`（建会话时同样的检查），什么也不改。
pub fn set_frequency_adjustment(&mut self, options: FrequencyAdjustmentOptions) -> Result<()> {
if !input::frequency_options_valid(options) {
return Err(EngineError::invalid(diagnostics::INVALID_SESSION_OPTIONS));
}
self.candidates_may_change();
self.input.frequency = options;
self.nine_key.set_frequency(options);
Ok(())
}
/// 当前的调频方式：建会话时给的，或之后 [`Self::set_frequency_adjustment`] 换上的。
pub fn frequency_adjustment(&self) -> FrequencyAdjustmentOptions {
self.input.frequency
}
/// Hand over the candidates withheld from a single-letter query; whether the list grew.
pub fn expand_initial_candidates(&mut self) -> bool {
self.input.pending_touch = None;
// Nine-key rows come from the spelling session rather than a dictionary query, so nothing is withheld there.
if self.nine_key.active() {
return false;
}
let grew = self.input.expand_initial_candidates();
if grew {
self.candidates_may_change();
}
grew
}
/// 设置前缀解码的组字光标（overlays.md §7.6）；位置限制在可编辑范围，不能越过本地模式的入口标记。`None` 回到末尾，九键组码时无操作。
pub fn set_caret(&mut self, caret: Option<usize>) {
self.candidates_may_change();
self.prediction.clear();
self.input.pending_touch = None;
// 五笔 14 键的组码不是逐个字母，没有可以落脚的光标位置。
if self.nine_key.active() || self.input.wubi_grid_composing() {
return;
}
self.input.set_caret(caret);
}
/// End of the complete pinyin units before the caret in `editing_text`; 0 while nine-key digits are active.
pub fn prefix_end(&self) -> usize {
if self.nine_key.active() {
return 0;
}
self.input.prefix_end()
}
/// The raw text after `prefix_end`, case kept; empty while nine-key digits are active.
pub fn pending_suffix(&self) -> String {
if self.nine_key.active() {
return String::new();
}
self.input.pending_suffix()
}
pub fn snapshot(&self) -> SessionSnapshot {
self.snapshot_with_display_options(true, false)
}
/// 给宿主画在屏幕上的快照：全拼的 `preedit` 按音节分开（双拼照 `shuangpin_preedit_uses_raw`），辅助码注释照常给出。[`Session::snapshot`] 的 `preedit` 保留全拼的按键原文，参考回放按它比对；其余字段两者相同。C 接口的 `msime_engine_state` 读的是这一份。
pub fn display_snapshot(&self) -> SessionSnapshot {
self.snapshot_with_display_options(true, true)
}
pub(crate) fn snapshot_for_host(&self, show_helpcode: bool) -> SessionSnapshot {
self.snapshot_with_display_options(show_helpcode, true)
}
fn snapshot_with_display_options(
&self,
show_helpcode: bool,
segmented_quanpin: bool,
) -> SessionSnapshot {
if !self.prediction.rows.is_empty() {
return SessionSnapshot {
prediction: true,
scheme: self.input.scheme(),
local_mode: self.input.local_mode,
spelling_symbols: self.input.spelling_symbols(),
shuangpin_profile: self.input.profile.kind.name().to_owned(),
candidates: self.prediction.rows.clone(),
candidate_sources: self.prediction.rows.iter().map(|row| row.source).collect(),
candidate_annotations: vec![String::new(); self.prediction.rows.len()],
candidate_answers_key: vec![false; self.prediction.rows.len()],
..SessionSnapshot::default()
};
}
if self.nine_key.active() {
return self.nine_key.snapshot();
}
let hide_helpcode = !show_helpcode
&& self.input.helpcode_enabled()
&& !self.input.local_mode.annotates_rows();
let input = &self.input;
let mut candidates = input.candidates().to_vec();
for item in &mut candidates {
input.apply_english_word_case(item.source, &mut item.word);
}
// 光标后编辑：候选仍是光标后那段的行，首选显示时前面接上固定的那段（由 runtime 在视图里接上），这样重排、释义和选择核对都按行本身的文字进行。
let caret_edit_suffix = input.caret_edit.active && input.conversion.is_none();
let caret_edit_prefix = input
.caret_edit_prefix()
.filter(|_| caret_edit_suffix && !candidates.is_empty())
.unwrap_or_default();
// 宿主显示全拼分词；参考回放的底层快照仍保留原文。
let segmented_preedit = (segmented_quanpin && input.scheme() == SchemeType::Quanpin)
|| (!self.shuangpin_preedit_uses_raw && input.scheme() == SchemeType::Shuangpin);
let preedit = if segmented_preedit
&& input.local_mode == LocalInputMode::None
&& !input.dedicated_english
{
input.pinyin_segmentation_with_cases().into_owned()
} else {
input.preedit()
};
SessionSnapshot {
prediction: false,
scheme: input.scheme(),
local_mode: input.local_mode,
spelling_symbols: input.spelling_symbols(),
preedit,
raw_segmentation: input.raw_segmentation(),
normalized_segmentation: input.normalized_segmentation(),
dedicated_english: input.dedicated_english,
editing_text: input.editing_text(),
caret_position: input.caret_position(),
nine_key_spellings: input.zhuyin_spellings(),
// 五笔 14 键的读音行显示首选的编码（就是预编辑），宿主 14 键的读音行照常读这一项。
nine_key_reading: if input.wubi_grid_composing() {
input.preedit()
} else {
String::new()
},
nine_key_single_character: false,
nine_key_strokes: String::new(),
answered_by_pinyin_fallback: input.answered_by_pinyin_fallback(),
wubi_unique_four_code: input.wubi_unique_four_code(),
shuangpin_profile: input.profile.kind.name().to_owned(),
candidate_sources: candidates.iter().map(|item| item.source).collect(),
multilingual_conversion: candidates
.iter()
.any(|item| item.source == CandidateSource::Multilingual)
.then(|| input.multilingual_conversion.clone())
.flatten(),
candidate_annotations: input.candidate_annotations(hide_helpcode),
// 纠错候选按原始按键长度消费；普通候选仍按 `pinyin`，两者都由组字推进判断。
candidate_answers_key: candidates
.iter()
.map(|item| {
// 占位行、网址补全和联系人不交给重排模型；联系人保留本地优先顺序。
!matches!(
item.source,
CandidateSource::AiPending
| CandidateSource::CloudPending
| CandidateSource::Contact
) && !input.is_url_completion(item)
&& input.selection_completes_composition(item)
})
.collect(),
candidate_list_open: input.candidate_list_open(),
conversion: input
.conversion
.as_ref()
.map(|edit| edit.text())
.unwrap_or_default(),
conversion_focus: input
.conversion
.as_ref()
.map_or((0, 0), |edit| edit.focus_span()),
caret_edit_suffix,
caret_edit_prefix,
candidates,
}
}
/// 返回候选词的完整五笔编码，仅供宿主显示反查结果；九宫格会话不沿用旧的普通候选反查。
pub fn candidate_wubi_code(&self, word: &str) -> Option<&str> {
if self.nine_key.active() {
return None;
}
self.input.engine.candidate_wubi_code(word)
}
/// 显示候选与原始候选同座且词面一致时复用已缓存的反查码；候选身份错位时返回 `None`，由宿主回退到按词入口。
pub(crate) fn candidate_wubi_code_at_if_item(
&self,
index: usize,
item: &WordItem,
) -> Option<&str> {
if self.nine_key.active() {
return None;
}
self.input
.engine
.candidate_wubi_code_at_if_item(index, item)
}
pub(crate) fn candidate_wubi_code_if_item(&self, item: &WordItem) -> Option<&str> {
if self.nine_key.active() {
return None;
}
self.input.engine.candidate_wubi_code_if_item(item)
}
/// Byte offsets into `editing_text` for pinyin-unit editing; empty when idle, in local modes, for non-pinyin schemes and during nine-key input. Read-only.
pub fn segment_raw_boundaries(&self) -> Vec<usize> {
if self.nine_key.active() {
return Vec::new();
}
self.input.segment_raw_boundaries()
}
pub fn online_query(&self) -> Option<OnlineQuery> {
if self.nine_key.active() {
return None;
}
self.input.online_query()
}
/// Whether an apostrophe now separates a unit from its target or one `/fy` word from the next, so a host or runtime that would finish the composition on punctuation hands it over as a character instead.
pub fn takes_local_separator(&self) -> bool {
!self.nine_key.active() && self.input.takes_local_separator()
}
/// The `/fy` translation request; see `InputSession::command_translation_query`.
pub fn command_translation_query(&self) -> Option<CommandTranslationQuery> {
if self.nine_key.active() {
return None;
}
self.input.command_translation_query()
}
/// Whether the translation now shows first; false (not an error) for a stale query.
pub fn apply_command_translation(
&mut self,
query: &CommandTranslationQuery,
translation: &str,
) -> bool {
if self.nine_key.active() {
return false;
}
let applied = self.input.apply_command_translation(query, translation);
if applied {
self.candidates_may_change();
}
applied
}
/// 插件指令要宿主去问的那一次；见 `InputSession::plugin_command_query`。
pub fn plugin_command_query(&self) -> Option<PluginCommandQuery> {
if self.nine_key.active() {
return None;
}
self.input.plugin_command_query()
}
/// 插件的行是否写进了会话；过期的查询返回 false（不是错误）。
pub fn apply_plugin_command_rows(
&mut self,
query: &PluginCommandQuery,
rows: &[(String, String)],
) -> bool {
if self.nine_key.active() {
return false;
}
let applied = self.input.apply_plugin_command_rows(query, rows);
if applied {
self.candidates_may_change();
}
applied
}
/// Whether the rows now show; false (not an error) for a stale query.
pub fn apply_online_candidates(
&mut self,
query: &OnlineQuery,
words: &[String],
source: CandidateSource,
) -> bool {
if self.nine_key.active() {
return false;
}
let applied = self.input.apply_online_candidates(query, words, source);
if applied {
self.candidates_may_change();
}
applied
}
/// Remove one online provider's rows from cached and visible candidates.
pub fn clear_online_candidates(&mut self, source: CandidateSource) {
self.candidates_may_change();
self.input.clear_online_candidates(source);
}
pub fn apply_online_candidate(
&mut self,
query: &OnlineQuery,
word: &str,
source: CandidateSource,
) -> bool {
if self.nine_key.active() {
return false;
}
let applied = self.input.apply_online_candidate(query, word, source);
if applied {
self.candidates_may_change();
}
applied
}
/// Grid commits bypass the input session, so the word after one must not read the word before it as its context (session.cpp:37-45).
fn after_nine_key(&mut self, result: KeyResult) -> KeyResult {
if result.commit.is_some() {
self.input.note_external_commit();
}
result
}
fn predict_after_commit(&mut self, selected: Option<WordItem>, result: &KeyResult) {
if !self.prediction.enabled
|| self.nine_key.active()
|| self.input.has_composition()
|| self.input.dedicated_english
|| self.input.local_mode != LocalInputMode::None
|| !matches!(
self.input.scheme(),
SchemeType::Quanpin | SchemeType::Shuangpin
)
{
return;
}
let Some(selected) = selected else { return };
if result.commit.as_deref() != Some(selected.word.as_str()) {
return;
}
let previous = selected
.sentence_words
.last()
.map_or(selected.word.as_str(), String::as_str);
self.show_prediction(&selected.word, &selected.canonical_pinyin, previous);
}
fn show_prediction(&mut self, word: &str, pinyin: &str, previous: &str) {
let personal = self
.input
.personal_context_applies()
.then_some(self.input.personal_context.as_ref());
self.prediction.show(word, pinyin, previous, personal);
}
}
/// The C++ registered `PersonalNgramStore::flush_all` with `atexit` (personal_ngram_store.cpp:255), so context learned in the last ~2 s reached the journal when the host quit. Rust runs no destructors for statics and `atexit` needs unsafe, so the session writes its journal's queue as it ends, which hosts do on deactivation and shutdown. A host that can exit without dropping its sessions (macOS `[NSApp terminate:]` runs `exit()`) calls [`crate::flush_personal_learning`] (host-api's `msime_client_flush_all`) or [`crate::shutdown`] from its will-terminate hook instead.
impl Drop for Session {
fn drop(&mut self) {
// Nobody is left to report to: a failed write stays queued and flagged in the store, and the next record reports it and schedules another try.
let _ = flush_journal(&self.journal);
// A host thread whose sessions are gone (a quiesced IME, a closed window) holds no journal handle.
release_thread_journal();
// The last session on this journal also closes the idle connections other threads keep to it, so a session created on one thread and ended on another leaves nothing open. Before the record below: closing the last connection to a WAL journal checkpoints it, which changes the files the record describes.
self.journal_use.end();
// Nothing of this session writes the journal after this point. A host-api session still holds its dictionary access here (its Runtime drops first), so no dictionary maintenance can change the file between the write above and this record.
note_settled(&self.journal);
}
}