拼音輸入法API開發解密---lua篇

   當今的拼音輸入法太多，如搜狗拼音輸入法，以及谷歌拼音輸入法，都增長了輸入法擴展功能，雖然競爭很激烈，但從技術上來講差很少。

   先介紹下谷歌輸入法擴展API功能。

開始----lua開發

爲了幫助開發者在谷歌拼音輸入法的基本輸入功能基礎上，開發和定義更豐富的擴展輸入功能，谷歌拼音輸入法提供了以Lua腳本編程語言爲基礎的輸入法擴展API。利用輸入法擴展API，開發者能夠編寫自定義的輸入功能。lua腳本語言也可開發遊戲項目。

先介紹下一段簡單的Lua腳本程序就能夠構成一個最基本的輸入法擴展模塊。下面是「Hello,World!」

代碼以下：

helloworld.lua

 
 
 
  
 function HelloWorld()   
 
 
  
 return "Hello,World!"   
 
 
  
 end   
 
 
  
 ime.register_command("hw", "HelloWorld", "test")  
 

 

這一段代碼由一個自定義的Lua函數和一行ime.register_command函數調用組成。自定義的Lua函數HelloWorld()簡單地返回一個Lua字符串"Hello,World!"，這代表該輸入法擴展函數被調用後，顯示給最終用戶的候選項爲"Hello,World!"。ime.register_command函數調用將自定義函數註冊爲谷歌拼音輸入法的一個命令擴展。其中，第一個參數"hw"表示該命令擴展在i擴展模式中對應的命令是"hw"，第二個參數表示該命令擴展對應的入口函數(自定義的Lua函數)是"HelloWorld"，第三個參數是顯示在i擴展模式命令列表內的簡短說明文字。

使用任何文本編輯器輸入上述程序後，以helloworld.lua爲文件名保存到安裝有谷歌拼音輸入法的計算機中。而後，打開谷歌拼音輸入法選項設置窗口，在"擴展"頁面中，點擊"安裝擴展包"按鈕，選擇保存在計算機內的helloworld.lua(也能夠從Windows資源管理器，右鍵單擊helloworld.lua文件，選擇「安裝到谷歌拼音輸入法」)。安裝後，打開記事本程序，切換到谷歌拼音輸入法，鍵入"ihw"，谷歌拼音輸入法的候選項窗口中將出現惟一候選項"Hello,World!"。

這一行的做用是將函數"HelloWorld"註冊爲谷歌拼音輸入法的一個整合擴展。第一個參數是擴展對應的入口函數"HelloWorld"，第二個參數是簡短說明文字，第三個參數給出但願將擴展關聯到哪一個或哪幾個用戶輸入串(這裏是字符串"hello")，第四個參數給出但願將擴展關聯到哪一個或哪幾個特定的候選詞(這裏是空表，表示不關聯)。

打開谷歌拼音輸入法選項設置窗口，在"擴展"頁面中，使用"移除擴展包"按鈕將剛纔安裝的helloworld.lua刪除，而後從新安裝更新後的helloworld.lua。打開記事本程序，切換到谷歌拼音輸入法，鍵入"hello"，谷歌拼音輸入法的候選項窗口中，除了出現一般的中文英文候選詞提示外，還將出現由整合擴展函數返回的候選項"Hello,World!"。

事實上，谷歌拼音輸入法提供的輸入法擴展API能夠用來開發各類不一樣的輸入體驗，例如，根據用戶輸入的參數返回相應的信息內容，查表輸入特定的文字信息，完成自定義的甚至包含隨機變量的計算並以不一樣形式返回結果，將用戶剛剛輸入的文字內容轉換爲另外一種表現形式，等等。谷歌拼音輸入法提供的i模式的缺省功能，包括時間和日期格式轉換，查星座，擲骰子，打印字符等，都是一些最簡單的示例。

本指南的後續內容詳細介紹了開發輸入法擴展所須要的各類知識。咱們也鼓勵開發者直接參考已有的示例程序。例如，i擴展模式的缺省功能是由安裝在如下位置的Lua腳本程序實現的：

XP: C:\Documents and Settings\All Users\Application Data\Google\Google Pinyin 2\Extensions\base.lua

Vista / Windows 7: C:\ProgramData\Google\Google Pinyin 2\Extensions\base.lua

三種不一樣的擴展方式

谷歌拼音輸入法擴展API提供了三種擴展拼音輸入法的方式：命令擴展、整合擴展與轉換器擴展。

命令擴展：將腳本程序中的某個入口函數關聯到一個兩字母長的自定義命令。當用戶先鍵入i而後鍵入該命令時，輸入法即激活該擴展函數，而後在候選項列表中顯示擴展函數返回的候選項結果。

命令擴展適用於那些用戶明確但願在特定場景下使用特定輸入功能，且候選項較多，或較複雜的狀況。例如，用戶明確但願根據生日查詢並輸入星座信息等。

整合擴展：將腳本程序中的某個入口函數關聯到特定的鍵盤輸入串，或特定的中英文候選項。當用戶使用拼音輸入法時，一旦用戶經過鍵盤輸入的字符串與整合擴展關聯的特定字符串(可包含通配符)匹配，或拼音輸入法解析出的某個候選項與整合擴展關聯的特定字符串(可包含通配符)匹配，輸入法即激活該擴展函數，並將擴展函數返回的候選項結果插入到候選項列表中。

整合擴展適用於那些在不妨礙用戶正常輸入的狀況下，根據當前輸入或候選內容，插入少數相關候選項的狀況。例如，用戶在輸入中文「時間」的同時，也可能但願直接輸入當前時間，這時，整合擴展直接把擴展函數返回的當前時間整合至候選項列表中，就顯得比較方便了。

轉換器擴展：將腳本程序中的某個入口函數註冊爲一個特定的轉換器。當用戶經過輸入法的用戶界面(如功能菜單)開啓該轉換器時，輸入法產生的每一個候選項被依次當作參數送入該轉換器函數，進行運算後，函數返回的結果將會替換掉原候選項的內容，被輸入法顯示在相應位置。

轉換器擴展必須由用戶主動開啓。一旦開啓，就會應用於全部候選項。所以，轉換器擴展適用於爲全部候選項增長裝飾、特效，或者對全部候選項按規則進行變換的情形。例如，爲候選項或候選項的每一個字增長星號修飾，直接在候選項的每一個字後面輸出該字對應的Unicode編碼，將簡體漢字變爲繁體漢字，等等。

下表對不一樣的擴展方式進行簡單的對比：

擴展方式	命令擴展	整合擴展	轉換器擴展
註冊方式	ime.register_command (...)	ime.register_trigger (...)	ime.register_converter (...)
適用範圍	用戶明確但願在特定場景下使用特定輸入功能，且候選項較多，或較複雜的狀況	在不妨礙用戶正常輸入的狀況下，根據當前輸入或候選內容，插入少數相關候選項的狀況	爲全部候選項增長裝飾、特效，或者對全部候選項按規則進行變換的情形
應用實例	根據輸入的生日查詢星座；列舉並輸入特定的字符畫	用戶輸入中文「時間」時，在候選項列表裏插入當前時間；用戶輸入中文「哈哈」時，在候選項列表插入相應的表情符號	爲候選項或候選項的每一個字增長星號修飾；直接在候選項的每一個字後面輸出該字對應的Unicode編碼；將簡體漢字變爲繁體漢字
激活方式	用戶輸入i加2字符長的命令，激活相應的命令擴展	用戶輸入的拼音字符串或輸入法產生的某個候選項與整合擴展關聯的特定字符串（可包含通配符）匹配時，激活相應的整合擴展	用戶從輸入法的用戶界面（如功能菜單）開啓特定的轉換器，激活相應的轉換器擴展

註冊命令擴展

在Lua腳本中，向谷歌拼音輸入法註冊一個命令擴展的基本語法是：

 
 
 
  
 ime.register_command(command_name, lua_function_name, description, leading, help)  
 

 

ime是提供給Lua腳本使用的，與輸入法內核交互的專用模塊。register_command是向谷歌拼音輸入法註冊新的i擴展模式命令擴展所使用的函數。函數的各參數含義以下：

◆ command_name

2字符長的字符串，必須由兩個英文字母(a-z)組成。定義了要註冊的命令名字。若是新註冊的命令名稱和此前已經註冊的某個命令重名(判斷重名時不區分大小寫)，則register_command函數調用失敗，新命令擴展沒法註冊到輸入法中。

◆ lua_function_name

字符串。給出此命令在i擴展模式中運行時對應的Lua入口函數。這必須是一個已經存在的，接收一個或零個參數的Lua函數。

◆ description

字符串。命令的簡短描述。此描述會顯示在i擴展模式的命令選擇界面中，向用戶簡要說明某命令的功能。不要使用太長的簡短描述，通常不要超過10個字符。

◆ leading [可省略]

字符串。用戶選擇此命令的候選項目時，可使用的快捷鍵，能夠是如下三個特定字符串之一：

"digit": 默認值。表示用1, 2, 3, ...這樣的數字做爲候選項選擇鍵。

"alpha": 表示用a, b, c, ...這樣的英文字母序列做爲候選項選擇鍵。

"none": 表示不使用候選項選擇鍵。

注：默認狀況下，輸入法使用1, 2, 3, ...數字鍵做爲候選項選擇鍵。可是，當i擴展模式的某個命令但願接收數字1, 2, 3, ...做爲本身的參數時，爲避免衝突，就不能使用"digit"方式的候選項選擇鍵了。同理，當命令但願接收包含英文字母的參數時，就不能使用"alpha"做爲候選項選擇鍵。

◆ help [可省略]

字符串。比description略長的幫助信息，但通常不要超過50個字。當用戶鍵入了"i"以及特定的命令名後，輸入法候選窗口的右上方會顯示此文字信息，用於提示用戶如何輸入後續參數。

lua_function_name給出的命令入口函數能夠接收一個或零個參數，例如：

 
 
 
  
 function my_entry_function()   
 
 
  
   -- 作某些處理並返回結果   
 
 
  
 end  
 

 

當入口函數接收一個參數時，輸入法會把用戶在i擴展模式中i+兩字母命令名輸完後繼續輸入的全部內容做爲一個字符串參數，傳給入口函數。例如，用戶前後鍵入「ihw123」，則，用戶激活的命令名是「hw」，輸入法調用該命令對應入口函數時，以字符串方式傳入參數「123」。入口函數能夠對參數進行運算處理，並返回對應的結果。例如：

function my_entry_function(argument)

-- 將參數argument轉換爲數字，計算並返回其平方根...

end

註冊命令擴展時傳入的提示信息description會在用戶看到i擴展模式的命令列表時顯示，以提示用戶該命令的功能。這個字符串應當儘可能簡短(不超過10個字符)。以下圖中的「擲骰子」，「打印字符」等，都是description：

註冊命令擴展時傳入的提示信息help會在用戶選中了某特定命令後，顯示在輸入法候選窗口的右上角。這個字符串能夠比description略長，但通常也不要超過50個字符。例如，下圖中用戶選擇了打印字符命令「zf」後，顯示出來的「請輸入字母或數字序列，例如hello」就是help的內容：

註冊整合擴展

在Lua腳本中，向谷歌拼音輸入法註冊一個整合擴展的基本語法是：

 
 
 
  
 ime.register_trigger(lua_function_name, description, input_trigger_strings, candidate_trigger_strings)  
 

 

ime是提供給Lua腳本使用的，與輸入法內核交互的專用模塊。register_trigger是向谷歌拼音輸入法註冊新的整合擴展所使用的函數。函數的各參數含義以下：

◆ lua_function_name

字符串。給出此擴展運行時對應的Lua入口函數。這必須是一個已經存在的，接收一個參數的Lua函數。

◆ description

字符串。擴展功能的簡短描述，向用戶簡要說明某擴展的功能。不要使用太長的簡短描述，通常不要超過10個字符。

◆ input_trigger_strings

一個字符串組成的Lua列表，包含零個或多個特定的由英文字母或通配符*組成的字符串。這裏給出的全部字符串在輸入法運行時將分別與用戶的輸入內容匹配，一旦用戶的輸入和給出的某個特定字符串相同(或使用通配符匹配成功)，註冊的擴展函數就會被調用，擴展函數返回的候選項結果將會被插入到輸入法的候選項列表中。

◆ candidate_trigger_strings

一個字符串組成的Lua列表，包含零個或多個特定的由英文、中文、數字等可顯示字符或通配符*組成的字符串。這裏給出的全部字符串在輸入法運行時將分別與輸入法獲得的候選項進行匹配，一旦候選項列表第一頁中某個候選項和給出的某個特定字符串相同(或使用通配符匹配成功)，註冊的擴展函數就會被調用，擴展函數返回的候選項結果將會被插入到輸入法的候選項列表中。

關於通配符匹配：input_trigger_strings和candidate_trigger_strings中的字符串能夠在開頭或結尾包含通配符*，表示前綴匹配或後綴匹配。例如：

◆ abc*

表示匹配前綴爲abc的任意字符串。例如，字符串abc，abcd，abcde均可以與之成功匹配。

◆ *abc

表示匹配後綴爲abc的任意字符串。例如，字符串abc，dabc，deabc均可以與之成功匹配。

使用ime.register_trigger註冊整合擴展時，請注意如下幾點：

◆ 參數input_trigger_strings和candidate_trigger_strings不能同時爲空表。

◆ 輸入法在激活整合擴展函數時，將優先匹配input_trigger_strings，而後再匹配candidate_trigger_strings。匹配candidate_trigger_strings時，會按照輸入法獲得的候選項順序依次嘗試。對每一次輸入，一旦找到了匹配，就只插入該匹配對應的擴展函數返回的候選項結果，再也不繼續嘗試其餘匹配。

◆ 雖然擴展函數能夠返回一個或多個結果，但對於整合擴展來講，目前只有第一個候選項結果會被插入到輸入法的候選項列表中。

◆ 目前一個整合擴展能夠經過input_trigger_strings和candidate_trigger_strings註冊的字符串數目是有限制的，通常不要超過200個。

◆ 目前整合擴展在匹配candidate_trigger_strings時，只會與候選項列表第一頁中的候選項進行匹配。

整合擴展的入口函數通常應接收一個參數。在激活整合擴展函數時，輸入法會把激活整合擴展函數的字符串(或者是用戶輸入的內容，或者是某個特定的候選項)做爲惟一的參數傳遞給入口函數。這樣，註冊了多個匹配字符串的整合擴展函數就能夠在被調用時經過參數知道到底是哪一個字符查激活了本身。固然，在不須要時，入口函數也能夠簡單地忽略這個參數。

註冊轉換器擴展

在Lua腳本中，向谷歌拼音輸入法註冊一個轉換器擴展的基本語法是：

 
 
 
  
 ime.register_converter(lua_function_name, description)  
 

 

ime是提供給Lua腳本使用的，與輸入法內核交互的專用模塊。register_converter是向谷歌拼音輸入法註冊新的轉換器擴展所使用的函數。函數的各參數含義以下：

◆ lua_function_name

字符串。給出此擴展運行時對應的Lua入口函數。這必須是一個已經存在的，接收一個參數的Lua函數。

◆ description

字符串。擴展功能的簡短描述，向用戶簡要說明某擴展的功能。不要使用太長的簡短描述，通常不要超過10個字符。對於轉換器擴展，此描述信息會被輸入法的用戶界面顯示給用戶，以便選擇特定的轉換器擴展。

用戶開啓轉換器時，輸入法會依次將每一個候選項做爲參數調用轉換器對應的Lua入口函數。也就是說，對於每一個候選項，Lua入口函數都被調用一次。

轉換器擴展對應的Lua入口函數應當返回且只返回一個結果，即返回對原候選項進行變換後的新候選項。若是不但願變換某個候選項，能夠將輸入參數的值直接返回。若是沒有返回任何結果，或返回的結果數目多於一個，則輸入法認爲該擴展函數沒有對候選項作任何變換。

安裝了轉換器擴展後，用戶能夠從輸入法的用戶界面啓動或關閉特定的轉換器。以下圖，從功能菜單開啓或關閉特定的轉換器：圖：

返回候選項

通常的，擴展對應的入口函數能夠返回一個或多個候選字符串。命令擴展會顯示全部返回的候選項，整合擴展目前只會將第一個候選項結果插入到輸入法的候選項列表中，而轉換器擴展則只接受返回一個候選字符串的入口函數。

返回的參數類型能夠是Lua字符串類型，也能夠是Lua數字類型，還能夠是Lua布爾類型。但這些返回值返回輸入法內核後，都會被轉換成字符串顯示給最終用戶，以便用戶選擇輸入。

要返回惟一的候選字符串，只要直接使用return語句返回字符串、數字或布爾值便可，例如：

 
 
 
  
 function TestString(argument)   
 
 
  
   -- 作某些處理   
 
 
  
   return "a string"   
 
 
  
 end   
 
 
  
   
 
 
  
 function TestNumber(argument)   
 
 
  
   -- 作某些處理   
 
 
  
   return 1234.56789   
 
 
  
 end   
 
 
  
   
 
 
  
 function TestBoolean(argument)   
 
 
  
   -- 作某些處理   
 
 
  
   return true   
 
 
  
 end   
 
 
  
   
 
 
  
 function TestAnotherBoolean(argument)   
 
 
  
   -- 作某些處理   
 
 
  
   return 3 > 2   
 
 
  
 end  
 

 

要返回兩個或更多結果，只要返回一個Lua的列表對象便可，例如：

 
 
 
  
 function TestTable(argument)   
 
 
  
   return {"abc", "def", "ghi", 123, true}   
 
 
  
 end  
 

 

列表中的每一個元素能夠是Lua字符串，數字或布爾值，但不能嵌套列表。列表中的每一個元素將對應於輸入法顯示給用戶的候選項列表中的一個候選項。上面這個函數返回的列表在輸入法中的顯示以下圖所示：

除了單行字符串結果外，命令擴展的入口函數還能夠返回一個或多個包含換行符的多行結果(其餘擴展方式，如整合擴展和轉換器擴展，目前不建議返回多行的結果)。換行符在Lua程序的字符串常量中用"\n"表示。例以下面的函數：

 
 
 
  
 function TestMultilines(argument)   
 
 
  
   return "line 1" .. "\n" .. "line 2" .. "\n" .. "line 3"   
 
 
  
 end  
 

 

多行結果在輸入法的候選窗口中被顯示爲「<字符畫>」，當用戶選擇輸入該候選項後，多行文本被插入到用戶當前文檔中，以下圖：

返回提示信息

對於命令擴展，當用戶剛輸入完i擴展模式的命令名稱，還沒有輸入命令參數時，入口函數將被調用，此時傳給入口函數的參數爲空字符串。這時，入口函數能夠經過返回一個提示信息表，來提示用戶有幾種預約義的候選參數，並在輸入法的候選窗口中，容許用戶直接選擇某個預約義參數。例如：

 
 
 
  
 function TestMetatables(argument)   
 
 
  
   if #argument == 0 then   
 
 
  
     -- 若是沒有參數，則返回提示信息表，以便用戶直接選擇預約義的參數"num"或"chs"   
 
 
  
     return { { suggest = "num", help = "數字123" },   
 
 
  
              { suggest = "chs", help = "中文一二三" },   
 
 
  
            }   
 
 
  
   elseif argument == "num" then   
 
 
  
     -- 若是參數是"num"（多是用戶鍵入的，也多是用戶根據提示信息表直接選擇的），則返回數字結果   
 
 
  
     return 123   
 
 
  
   elseif argument == "chs" then   
 
 
  
     -- 若是參數是"chs"（多是用戶鍵入的，也多是用戶根據提示信息表直接選擇的），則返回中文結果   
 
 
  
     return "一二三"   
 
 
  
   end   
 
 
  
 end  
 

 

返回的提示信息表必須符合上述格式，即，表中的每一個元素都是一個子表，每一個子表內有兩個元素：鍵名suggset的元素表示要提示用戶輸入的一個候選參數，鍵名help的元素表示對該參數的簡短說明文字(不要超過10個字符)。上述入口函數在用戶沒有輸入參數時，輸入法顯示的提示窗口以下圖：

這時，用戶能夠試用上下鍵，翻頁鍵和鼠標選擇本身要輸入的參數，也能夠直接用鍵盤輸入。

其餘擴展方式，如整合擴展和轉換器擴展，不支持提示選擇參數功能，它們將忽略入口函數返回的此類提示信息。

使用ime模塊

在開發者編寫的Lua腳本中，代碼除了能夠調用Lua自己提供的各模塊功能(是標準Lua運行環境所提供功能的一個子集)，還可使用ime模塊訪問輸入法的相關信息，以實現與輸入法有關的特定功能。

例如，可使用ime模塊的get_last_commit()函數得到用戶上一次鍵入的字符串，並根據字符串的內容進行相應的計算，返回特定結果。好比，用戶鍵入了「你好」，而後使用i擴展模式中的某個功能，該功能看到「你好」後，自動返回「hello」。實現這一簡單邏輯的代碼以下：

 
 
 
  
 function TestConvertHello()   
 
 
  
   if ime.get_last_commit() == "你好" then   
 
 
  
     return "hello"   
 
 
  
   else   
 
 
  
     return "not found"   
 
 
  
   end   
 
 
  
 end  
 

 

更詳細的信息請參見API參考一節中有關ime模塊的部分。

錯誤處理

Lua入口函數接收沒法處理的參數，或者發生其餘內部錯誤時，能夠簡單地不返回任何參數，或者使用Lua語言內置的error()函數向輸入法報告錯誤信息，例如：

 
 
 
  
 function TestIgnoreError(argument)   
 
 
  
   if #argument > 5 then   
 
 
  
     return   
 
 
  
   end   
 
 
  
   return 123   
 
 
  
 end   
 
 
  
   
 
 
  
 function TestReportError(argument)   
 
 
  
   if #argument > 5 then   
 
 
  
     error("argument length > 5")   
 
 
  
   end   
 
 
  
   return 123   
 
 
  
 end  
 

 

使用error()函數報告的錯誤信息不會在輸入法用戶界面中顯示，但可使用控制檯工具測試腳本程序並查看錯誤信息。參見下面的開發與調試一節。

開發和調試

輸入法擴展腳本程序可使用任何源代碼/文本編輯器建立。在將輸入法擴展包安裝到谷歌拼音輸入法以前，可使用控制檯工具測試擴展程序，以確保程序功能正確。請從如下連接下載用於開發調試谷歌拼音輸入法擴展腳本的控制檯工具：

下載控制檯工具 (GooglePinyinApiConsole.exe)http://dl.google.com/pinyin/v2/GooglePinyinApiConsole.exe

在命令行運行控制檯工具GooglePinyinApiConsole.exe時，須要給出的命令行參數是一個或多個待測試的腳本文件路徑，控制檯工具會加載全部指定的輸入法擴展腳本，並啓動一個交互式界面，供開發者測試執行擴展模式。例如：

 
 
 
  
 GooglePinyinApiConsole.exe ext1.lua ext2.lua ext3.lua  
 

 

在控制檯工具的交互式界面中，鍵入"help"，能夠查看幫助信息：

i - 列出全部已註冊的命令擴展

i [COMMAND] - 無參數執行某命令擴展

i [COMMAND] [ARGUMENT] - 有參數執行某命令擴展

g [TRIGGER_STRING] - 嘗試利用某字符串參數激活整合擴展

c - 列出全部已註冊的轉換器擴展

c [FUNCTION] [STRING] - 測試轉換器函數

quit - 退出控制檯工具

help - 顯示幫助信息

當腳本加載或執行過程當中發生錯誤時，控制檯工具會打印顯示錯誤信息。錯誤信息包括髮生錯誤的腳本文件名，錯誤行號，錯誤內容等。

控制檯工具並非真實的輸入法運行環境，所以，一些和輸入法特定功能相關的接口，例如，ime.get_last_commit()，在控制檯運行的腳本中沒法獲得實時的輸入法相關信息，這時，此類函數的返回值是簡單的固定字符串，如「測試」。整合擴展也沒法像在輸入法中那樣，將結果插入在輸入法的候選項列表中。

下圖是顯示了使用控制檯工具測試缺省輸入法擴展包中各擴展功能的情形：

最後講一講Lua腳本語言

目前，谷歌拼音輸入法擴展API只提供了Lua一種開發語言。Lua是一種體積小巧卻功能強大的動態腳本編程語言，普遍用於網絡遊戲等應用的插件或擴展功能的開發。對於一個有JavaScript語言、VBScript語言或者Python語言開發經驗的開發者來講，學習Lua語言並不困難。請參考如下網址得到關於Lua語言的各類信息：

Lua編程語言

Lua程序設計語言

在輸入法環境中，每一個用戶安裝的輸入法擴展都是一個獨立的Lua語言模塊，每一個模塊在本身的名字空間中運行。也就是說，不一樣模塊間的同名符號不會衝突，但不一樣模塊間也沒法相互進行功能調用。用戶安裝的輸入法擴展只能調用API參考一節描述的Lua內置功能函數和ime模塊提供的輸入法相關函數。

API參考

使用Lua語言編寫的輸入法擴展程序保存在磁盤上時，推薦使用UTF-8編碼的文本文件。文本文件能夠包含也能夠不包含BOM文件頭。沒有BOM文件頭時，IME缺省認爲按UTF-8編碼加載。

使用Lua語言編寫的輸入法擴展程序可使用如下內置函數。除了ime模塊提供的輸入法相關函數外，這些函數是標準Lua運行環境的一個子集。所以，在將已有的Lua程序移植到輸入法擴展程序以前，請確認程序使用的函數在下表所涵蓋的範圍內。

如下凡屬於Lua標準運行環境的函數，均只給出簡要的功能說明。詳細用法請參見Lua語言標準函數庫的說明。

基本功能函數

◆ assert (v [, message])

斷言。若是v的值是非(nil或false)，就報告錯誤。

◆ error (message [, level])

報告錯誤。

◆ ipairs (t)

迭代器函數。用於對列表中元素的(序號，值)進行迭代。

◆ loadstring (string [, chunkname])

加載並執行字符串。

◆ next (table [, index])

用於遍歷列表的每一個元素。

◆ pairs (t)

迭代器函數。用於對列表中元素的(鍵，值)進行迭代。

◆ select (index, ...)

返回變長參數列表中從index以後開始的全部參數。

◆ tonumber (e [, base])

轉換爲數字。

◆ tostring (e)

轉換爲字符串。

◆ type (v)

返回參數的類型名。

◆ unpack (list [, i [, j]])

返回列表中的各個元素。

字符串處理函數

◆ string.byte (s [, i [, j]])

返回字符內部編碼。

◆ string.char (···)

返回內部編碼對應的字符串。

◆ string.find (s, pattern [, init [, plain]])

字符串查找。

◆ string.format (formatstring, ···)

字符串格式化。

◆ string.gmatch (s, pattern)

迭代器函數。用於在字符串中對全部匹配項進行迭代。

◆ string.gsub (s, pattern, repl [, n])

字符串全局替換。

◆ string.len (s)

返回字符串長度。

◆ string.lower (s)

轉換爲小寫。

◆ string.match (s, pattern [, init])

字符串匹配。

◆ string.rep (s, n)

重複字符串n次。

◆ string.reverse (s)

字符串反轉。

◆ string.sub (s, i [, j])

字符串替換。

◆ string.upper (s)

轉換爲大寫。

日期和時間函數

◆ os.date ([format [, time]])

返回格式化的日期時間字符串。

◆ os.difftime (t2, t1)

返回兩個時間相差的秒數。

◆ os.time ([table])

返回當前日期，或指定的日期。

數學函數

◆ math.abs (x)

絕對值。

◆ math.acos (x)

反餘弦。

◆ math.asin (x)

反正弦。

◆ math.atan (x)

反正切。

◆ math.ceil (x)

向上取整。

◆ math.cos (x)

餘弦。

◆ math.cosh (x)

雙曲餘弦。

◆ math.deg (x)

弧度轉角度。

◆ math.exp (x)

計算ex

◆ math.floor (x)

向下取整。

◆ math.fmod (x, y)

浮點數取模。

◆ math.frexp (x)

返回使x = m2e成立的m和e

◆ math.ldexp (m, e)

計算m2e

◆ math.log (x)

計算天然對數。

◆ math.log10 (x)

計算經常使用對數。

◆ math.max (x, ···)

求最大值。

◆ math.min (x, ···)

求最小值。

◆ math.modf (x)

返回浮點數的整數和小數部分。

◆ math.pi

返回π值。

◆ math.pow (x, y)

計算xy

◆ math.rad (x)

角度轉弧度。

◆ math.random ([m [, n]])

生成僞隨機數。

◆ math.randomseed (x)

設置隨機數種子。

◆ math.sin (x)

正弦。

◆ math.sinh (x)

雙曲正弦。

◆ math.sqrt (x)

平方根。

◆ math.tan (x)

正切。

◆ math.tanh (x)

雙曲正切。

表處理函數

◆ table.concat (table [, sep [, i [, j]]])

鏈接列表元素。

◆ table.insert (table, [pos,] value)

插入元素。

◆ table.maxn (table)

返回最大整數索引號。

◆ table.remove (table [, pos])

刪除元素。

◆ table.sort (table [, comp])

排序。

ime模塊提供的輸入法相關函數

註冊輸入法模塊相關函數

◆ ime.register_command (command_name, lua_function_name, description [, leading [, help]])

註冊命令擴展。詳細說明參見注冊命令擴展。

◆ ime.register_trigger (lua_function_name, description, input_trigger_strings, candidate_trigger_strings)

註冊整合擴展。詳細說明參見注冊整合擴展。

◆ ime.register_converter (lua_function_name, description)

註冊轉換器擴展。詳細說明參見注冊轉換器擴展。

輸入法信息相關函數

◆ ime.get_version ()

以字符串方式返回當前輸入法的版本號。

◆ ime.get_last_commit ()

返回用戶經過谷歌拼音輸入法輸入的上一個字符串。

實用工具函數

◆ ime.int_to_hex_string(value [, width])

將整數值value轉換成16進製表示的字符串。可選參數width指定告終果字符串的最小長度，不足最小長度時，高位用"0"補齊。

◆ ime.join_string (str_list, sep)

將str_list列表中的全部字符串鏈接成一個大字符串，並使用sep做爲鏈接字符，返回結果字符串。

◆ ime.parse_mapping (src_string, line_sep, key_value_sep, values_sep)

字符串src_string是一個用字符串方式表示的<鍵, 一個或多個值>的映射表，每一行表示一個鍵與其值的映射，行與行之間的分隔字符是line_sep，每行內鍵與後續的一個或多個值之間的分隔字符是key_value_sep，多個值之間的分隔字符是values_sep。ime.parse_mapping解析此格式的字符串，將其轉換爲Lua語言可直接使用的列表。結果列表的格式爲{key1={value1, value2, ...}, key2={value1, value2, ...}, ...}。此工具函數的典型應用實例是：在輸入法擴展模塊中預置一個字符串形式、易於閱讀和編輯的映射表(好比一種漢字編碼到對應的一個或多個漢字的映射)，而後在擴展模塊中用此函數解析該映射表，以便Lua代碼快速查詢。

示例代碼：

 
 
 
  
 _MAPPING_TABLE = [[   
 
 
  
 a 啊   
 
 
  
 b 不,吧   
 
 
  
 c 從,穿,出   
 
 
  
 ]]   
 
 
  
   
 
 
  
 _MAPPING = ime.parse_mapping(_MAPPING_TABLE, "\n", " ", ",")   
 
 
  
   
 
 
  
 function Lookup(input)   
 
 
  
   if _MAPPING[input] then   
 
 
  
     return _MAPPING[input]   
 
 
  
   else   
 
 
  
     error("Invalid argument")   
 
 
  
   end   
 
 
  
 end   
 
 
  
   
 
 
  
 ime.register_command("lp", "Lookup", "mapping lookup")  
 

 

◆ ime.split_string (str, sep)

根據分隔字符sep，將字符串str拆分爲一組字符串，返回這一組字符串組成的列表。

◆ ime.trim_string (str)

去除字符串str左右兩邊的空白字符，返回結果字符串。

◆ ime.trim_string_left (str)

去除字符串str左邊的空白字符，返回結果字符串。

◆ ime.trim_string_right (str)

去除字符串str右邊的空白字符，返回結果字符串。

◆ ime.utf8_to_utf16 (str)

將UTF-8編碼的字符串轉換爲UTF-16編碼的字符串，返回的結果字符串以"\0\0"結尾。

◆ ime.utf16_to_utf8 (str)

將UTF-16編碼的字符串轉換爲UTF-8編碼。

輸入法擴展開發API介紹完畢

end