CIN 標準（v2.4）

更新日期：

v2.4: 2023年12月21日。
v2.3: 2023年09月15日。
v2.2: 2023年06月20日。
v2.1: 2023年06月17日。
v2.0: 2022年10月19日。

目前暫時稱其為 CIN2，但保留 VCIN 這個備用名稱、以便在格式標準制定方面出現政變時的不時之需。

為什麼制定這個標準

CIN 是非常古老的輸入法碼表格式，最開始作為輸入法原始碼表用於劉德華（Edward）開發的 XCIN 中文輸入法模組、且在之後成為 OpenVanilla for macOS 的即讀碼表格式。二十餘年來，該格式幾乎沒有任何演進、不支援一些新的特性（比如：對萬能花牌鍵（萬用字元）的定義、對詞頻資料的承載，等）。

威注音輸入法 2.9.0 引入了 CIN 支援、且稱其為「磁帶格式」（因為會像是磁帶一樣一次性順序讀取的輸入法表格資料），但也意識到這個格式需要一些進化，就制定了這個規範。

具體內容規範

1. 檔案頭

[2.0] CIN2 推薦使用單個 ASCII 空格作為分欄符號。為了應對「使用者自 Microsoft Excel 等試算表軟體複製資料到磁帶檔案內」的情況，可以事先偵測 Tab 字符的存無：如果有的話，以 Tab 作為 delimiter。
[2.0] CIN2 不要求檔案是否以 %gen_inp 開頭，但在該開頭缺失的情況下、得要求以 %ename 開頭。另外，CIN2 標準對內容的忽略方法：以段落開頭結尾來規定要讀入的內容；在段落外部的內容，除非包含特定的特徵字串（比如像是 %wildcardkey 這樣的），否則會被無視。
[2.0] CIN2 要求的磁帶名稱定義方法：%ename 決定磁帶的英文名、%cname 決定磁帶的最優先的 CJK 名稱。至於 %sname 則是英文縮寫命名。此外，還有 %intlname 單行定義：用分號劃分語言區域，每個區域採 名稱:語言標記 的形式來記錄資料。一般情況下，%intlname 應該被解析讀取之後優先用於介面顯示。然而需注意 _ 符號在這一行會被自動取代為空格、以便讓英文名支援空格。比如說 Haifeng_Wubi 的話，讀取結果就是 Haifeng Wubi。至於語言標記，除了「需要用 - 而非 _ 來寫標記」以外，還請使用諸如 zh-Hans, zh-Hant-HK, zh-Hant-TW 這樣的現代標記來取代諸如 zh-CN, zh-TW, zh-HK 這樣的被淘汰的標記。定義範例如下：
```
 %ename Wubi
 %cname 五笔
 %sname WUBI
 %intlname Haifeng_Wubi:en;海峰五笔:zh-Hans;海峰五筆:zh-Hant
```
[2.0] CIN2 不再要求 %encoding 欄位。需注意的是：CIN2 在沒有設定該欄位的情況下可能只會被當 UTF-8 來讀取。
[2.0] CIN2 的 %selkey 可能會被輸入法開發者無視。但定義了總沒差。[2.1] 版開始，此處定義的選字鍵可能會被優先用作 %quick 簡碼的選字鍵。
[2.0] CIN2 的 %endkey 可能會被輸入法開發者無視，除非用來做基於「聲調確認漢字」這個做法來實現的音韻類輸入法。
[2.0] CIN2 的花牌鍵 %wildcardkey 允許使用者僅敲一個或幾個不完全的起始碼就可以叫出可能的選字結果。只有第一個字符才會生效。也就是說，一份磁帶只允許出現單個花牌鍵。

一個最顯著的例子就是五筆輸入法的「Z」鍵，可以在 %keyname 章節之前插入 %wildcardkey z 來定義。另外，威注音輸入法因為本身就是注音輸入法的緣故，所以在磁帶模式下的分號鍵「;」也可以在嘸蝦米的磁帶檔案當中定義為花牌鍵，可以在 %keyname 章節之前插入 %wildcardkey ; 來定義。
[2.0] %keyname 章節定義該磁帶要用到的字根、以及其對應的按鍵符號，每行格式為 按鍵符號顯示字根。該章節的資料將自動定義「該輸入法允許用來組字的按鍵」及其在輸入法的組字區當中顯示出來的字根字符。該章節以 %keyname begin 行開始，以 %keyname end 行結束。

注意：%keyname 章節嚴禁包含花牌鍵，否則花牌鍵會失效。
[2.0] %chardef 章節定義字根，每行格式為 用到的字根對應的按鍵符號字串對應的輸入字詞。該章節以 %chardef begin 行開始，以 %chardef end 行結束。該章節的資料將自動定義「該輸入法最大的組字長度」。在讀取該章節之前，如果已經成功讀取且生成 %wildcardkey 的話，則在讀取該 %chardef 章節時可以順勢生成另一個專門給花牌鍵使用的碼表辭典。另外，%chardef 當中用以組成「超過一個字元的字根」的鍵絕對不可以包含 %selkey 內出現過的字元，否則會給程式支援實作製造一些無法完美解決的難題、導致「不得不給某些磁帶表格開小灶」的情況。如果這種鍵有包含 %selkey 內出現過的字元的話，則該當磁帶模組得自動要求該選字鍵「必須摁住 Shift 才能生效」。

例外情形 [2.2]：這種鍵有包含 %selkey 內出現過的字元，但這種鍵出現在 %symboldef 章節當中的話，哪怕 %symboldef 章節與 %chardef 章節交叉、或被後者包含，也不用觸發上述禁則，因為符合 CIN 2.2 標準的輸入法會對 %symboldef 章節有專門的處理。

[2.0] %octagram begin 至 %octagram end 之間則是詞語頻次資料（威注音與 RIME 均稱之為「八股文」）。第三欄資料（可有可無）為對應字根、方便根據同一個字詞的不同字根安排不同的頻次統計資料。第一欄與第二欄分別為「字詞」與「統計頻次」。在讀取該章節時，可以順勢生成一些統計資料、方便該 CIN 資料模組在被請求資料時就地生成對數權重資料。
[2.1] %quick begin 至 %quick end 之間則是簡碼資料章節：每一行對應的 value 是單個字串、會被輸入法逐字拆分成一組候選字詞陣列。該章節得在 keyname 與 chardef 章節之間。比較經典的範例可以參見為 GCIN 設計的（基於 CIN1 標準的）行列三十輸入法的表格。
[2.1] %nullcandidate 用來指明 %quick 章節給出的候選字當中有哪一種字元是無效的。您只能指定某一種字元為無效簡碼候選字。
[2.2] 如果有用特殊命令觸發符號選單的話，相關章節得用 %symboldef begin 行開始，以 %symboldef end 行結束。%symboldef 章節或可置於 %chardef 內，以使其不破壞 CIN1 輸入法對此類表格的支援特性。
[2.3] 與%quick 章節有關：如果你希望與該章節有關的快速打字功能在檢索時全碼檢索、而不是以給定碼開頭檢索的話，請勿在磁帶檔案的檔案頭內插入 %flag_disp_partial_match 這一行。反之的話，請插入之。
[2.4] %keys_to_directly_commit 用來讓輸入法故意放棄對被該行參數值包括的字元對應的按鍵訊息的「標點符號/字母」輸入處理。這可以用來略過輸入法本身對某些按鍵內建的原廠標點符號資料定義。

以上內容，以一款五筆輸入法的磁帶而言，其範例結構：

# 該磁帶（CIN 表格）檔案僅供格式示範之用途，使用體驗不受威注音專案保證。請依個人需求自備磁帶檔案。
# 八股文詞頻資料取自 CNCorpus。
%ename Wubi:en;五笔:zh_CN;五筆:zh
%cname 五笔
%sname WUBI
%intlname Haifeng_Wubi:en;海峰五笔:zh-Hans;海峰五筆:zh-Hant
%selkey 1234567890
%wildcardkey z
%nullcandidate 💩
%keyname begin
a 工
b 子
c 又
d 大
e 月
f 土
g 王
h 目
i 水
j 日
k 口
l 田
m 山
n 已
o 火
p 之
q 金
r 白
s 木
t 禾
u 立
v 女
w 人
x 幺
y 言
%keyname end
%quick begin
w 人从众💩💩💩💩💩💩💩
%quick end
%chardef begin
aa 式
aaa 工
aaaa 工
aad 式
aadk 匿
aadn 慝
aadn 葚
aadw 萁
%symboldef begin
'1 ⎋
'1 ⏏
%symboldef end
......
%chardef end
%octagram begin
的 744863
了 130191
在 118823
是 118527
和 83958
一 81119
这 65146
有 53556
他 52912
我 52728
也 47908
不 46965
就 44947
地 42332
......
%octagram end

  

在 chinese-opendesktop/cin-tables 倉庫內有很多 CIN1 格式的磁帶檔案，可供使用者們自行補充相關內容、使其成為 CIN2 格式。

如果您希望使用「行列30」輸入法的表格的話，請洽 Gontera 所維護的倉庫：gontera/array30/tree/master/cin2

2. 程式實作範例

自 2.9.1 版開始，macOS 版威注音輸入法的倉庫內的「LMCassette.swift」檔案可用作範例。有些參數沒被威注音使用到，所以相關的實作不是很充分。

$ EOF.