喜歡使用 Sublime Text 的朋友們都知道，Sublime Text 相當于 Linux 上的 Vim，它們都具有很強的可擴展功能，功能多樣的同時速度也很快，對于處理小型文件和項目效率特別高，因此如果不是特別復雜的項目，我一般都是用 Sublime Text 編寫以及編譯的。

然而在用 Sublime Text 開發(fā)的過程中，我發(fā)現(xiàn)了一個問題：Sublime Text 本身的自動完成功能只搜索當前視圖中正在編輯文件的函數(shù)，當我想用其他文件中自定義的函數(shù)時，是沒有自動完成功能的。而當自定義函數(shù)過多時，效率會大大降低，于是我開始尋找具有相關功能的插件。

一開始我用了非常熱門的 “SublimeCodeIntel” 插件，試了一下的確非常好用，但是可惜的是，這個插件不支持 C/C++，而且占用的空間非常大，追求簡潔輕便的我不得不另辟蹊徑。后來又找到一款 “All AutoComplete” 插件，這款插件擴展了 Sublime Text 默認的自動完成功能，可以在當前視圖打開的所有文件里面尋找定義的函數(shù)和變量，盡管用起來效果不錯，但是它的問題也很明顯，必須要同時打開多個文件才行，非常不方便，于是我又放棄了。

在 Package Control 上找了許久，也沒能找到我想要的插件，于是我開始考慮不如自己寫一個這樣的插件，剛好借此機會入門 Python。這時我剛好想到能不能利用 CTags，它能把當前項目中的所有自定義函數(shù)提取出來，生成 .tags 文件，并提供符號跳轉功能，只要提取 .tags 文件里面的信息，用正則匹配，然后添加到 Sublime Text 的自動完成函數(shù)中不就行了。

為了完成這個插件，我在網上搜索相關信息，找到相關素材并重新構思了一下，同時參考了 All Complete 插件的源碼。

需要提一下，在 Sublime Text 下安裝 CTags 的方法這里不會提到，因此麻煩各位自行查詢。

插件構思

• 讀取設置，設置中添加的語言禁用插件功能

• 檢測 .tag 文件是否存在，不存在則直接 return

• 讀取當前文件夾中的 .tag 文件

• 正則匹配函數(shù)名

• 正則匹配函數(shù)體

• 添加到自動完成的接口上

開始編寫

新建插件

剛開始接觸 Sublime Text 插件的編寫，當然需要先了解 Sublime Text 提供的各種接口，為此，我去 Sublime Text 的官網找到了相關文檔：How to Create a Sublime Text Plugin，以及 Sublime Text Unofficial Documentation。

首先，在 Sublime Text  中選擇 “Tools -> Developer -> New Plugin” 新建一個最基本的插件文檔：

import sublime
import sublime_plugin
 
class ExampleCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        self.view.insert(edit, 0, "Hello, World!")

這里的 sublime 和 sublime_plugin 是 Sublime 必需的模塊，其中具體的類和方法可以參考官方的 API Reference。

接著，把這個文件保存到 Package文件夾（默認的保存位置 User 文件夾的上一層）的 CTagsAutoComplete 文件夾（新建）下，并命名為 CTagsAutoComplete.py。盡管命名并沒有什么限制，但***還是以插件的名稱來統(tǒng)一命名。

然后回到 Sublime Text 中，通過快捷鍵 Ctrl+` 進入 Sublime Text 的 Command Console，然后輸入 view.run_command('example')，如果下方顯示 “Hello World”，說明插件已經正常加載。

這里之所以直接用 'example'，是因為 Command 命令的名稱是根據大寫字符進行拆分的，例子中的 ExampleCommand 在 Command 中 為 'example_command'，直接輸入 'example' 也可以訪問。

文中的術語

• Window：Sublime Text 的當前窗口對象

• View：Sublime Text 當前窗口中打開的視圖對象

• Command Palette：Sublime Text 中通過快捷鍵 Ctrl+Shift+P 打開的交互式列表

確定插件接口類型

Sublime Text 下的插件命令有 3 種命令類型（都來自于 sublime_plugin 模塊）：

• TextCommand Class：通過 View 對象提供對選定文件/緩沖區(qū)的內容的訪問。

• WindowCommand Class：通過 Window 對象提供當前窗口的引用

• ApplicationCommand Class：這個類沒有引用任何特定窗口或文件/緩沖區(qū)，因此很少使用

2 種事件監(jiān)聽類型：

• EventListener Class：監(jiān)聽 Sublime Text 中各種事件并執(zhí)行一次命令

• ViewEventListener Class：為 EventListener 提供類似事件處理的類，但綁定到特定的 view。

2 種輸入處理程序：

• TextInputHandler Class：可用于接受 Command Palette 中的文本輸入。

• ListInputHandler Class：可用于接受來自 Command Palette 中列表項的選擇輸入。

因為我要實現(xiàn)的功能比較簡單，只需要監(jiān)聽輸入事件并觸發(fā)自動完成功能，因此需要用到 EventListener Class。在該類下面找到了 on_query_completions 方法用來處理觸發(fā)自動完成時執(zhí)行的命令。接著修改一下剛才的代碼：

import sublime
import sublime_plugin
 
class CTagsAutoComplete(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):

• view：當前視圖

• prefix：觸發(fā)自動完成時輸入的文字

• locations: 觸發(fā)自動完成時輸入在緩存區(qū)中的位置，可以通過這個參數(shù)判斷語言來執(zhí)行不同命令

• 返回類型：

  • return None
  • return [["trigger \t hint", "contents"]...]，其中 \t hint 為可選內容，給自動完成的函數(shù)名稱添加一個提示
  • return (results, flag)，其中 results 是包含自動完成語句的 list，如上；flag 是一個額外參數(shù)，可用來控制是否顯示 Sublime Text 自帶的自動完成功能

讀取 CTags 文件

為了讀取 .tag 文件，首先得判斷當前項目是否打開，同時 .tag 文件是否存在，然后讀取 .tag 文件中的所有內容：

import sublime
import sublime_plugin
import os
import re
 
class CTagsAutoComplete(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):
        results = []
 
        ctags_paths = [folder + '\.tags' for folder in view.window().folders()]
        ctags_rows  = []
 
        for ctags_path in ctags_paths:
            if not is_file_exist(view, ctags_path):
                return []
            ctags_path = str(ctags_path)
            ctags_file = open(ctags_path, encoding = 'utf-8')
            ctags_rows += ctags_file.readlines()
            ctags_file.close()
 
def is_file_exist(view, file):
    if (not view.window().folders() or not os.path.exists(file)):
        return False
    return True

通過上述操作，即可讀取當前項目下所有的 .tag 文件中的內容。

分析 CTags 文件

首先是獲取 .tags 文件中，包含 prefix 的行：

for rows in ctags_rows:
    target = re.findall('^' + prefix + '.*', rows)

一旦找到，就通過正則表達式對該行數(shù)據進行處理：

if target:
    matched = re.split('\t', str(target[0]))
    trigger = matched[0] # 返回的***個參數(shù)，函數(shù)名稱
    trigger += '\t(%s)' % 'CTags' # 給函數(shù)名稱后加上標識 'CTags'
    contents = re.findall(prefix + '[0-9a-zA-Z_]*\(.*\)', str(matched[2])) # 返回的第二個參數(shù)，函數(shù)的具體定義
    if (len(matched) > 1 and contents):
        results.append((trigger, contents[0]))
        results = list(set(results)) # 去除重復的函數(shù)
        results.sort() # 排序

處理完成之后就可以返回了，考慮到***只顯示 .tags 中的函數(shù)，我不需要顯示 Sublime Text 自帶的自動完成功能（提取當前頁面中的變量和函數(shù)），因此我的返回結果如下：

return (results, sublime.INHIBIT_WORD_COMPLETIONS | sublime.INHIBIT_EXPLICIT_COMPLETIONS)

添加配置文件

考慮到能夠關閉插件的功能，因此需要添加一個配置文件，用來指定不開啟插件功能的語言，這里我參考了 “All AutoComplete” 的代碼：

def plugin_loaded():
    global settings
    settings = sublime.load_settings('CTagsAutoComplete.sublime-settings')
 
def is_disabled_in(scope):
    excluded_scopes = settings.get("exclude_from_completion", [])
    for excluded_scope in excluded_scopes:
        if scope.find(excluded_scope) != -1:
            return True
    return False
 
if is_disabled_in(view.scope_name(locations[0])):
    return []

這里用到的配置文件需要添加到插件所在的文件夾中，名稱為 CTagsAutoComplete.sublime-settings，其內容為：

{
    // An array of syntax names to exclude from being autocompleted.
    "exclude_from_completion": [
        "css",
        "html"
    ]
}

添加設置文件

有了配置文件，還需要在 Sublime Text 的 “Preferences -> Package settings” 下添加相應的設置，同樣也是放在插件所在文件夾中，名稱為 Main.sublime-menu：

[
    {
        "caption": "Preferences",
        "mnemonic": "n",
        "id": "preferences",
        "children": [
            {
                "caption": "Package Settings",
                "mnemonic": "P",
                "id": "package-settings",
                "children": [
                    {
                        "caption": "CTagsAutoComplete",
                        "children": [
                            {
                                "command": "open_file",
                                "args": {
                                    "file": "${packages}/CTagsAutoComplete/CTagsAutoComplete.sublime-settings"
                                },
                                "caption": "Settings"
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

總結

首先給出插件的完整源碼：

import sublime
import sublime_plugin
import os
import re
 
def plugin_loaded():
    global settings
    settings = sublime.load_settings('CTagsAutoComplete.sublime-settings')
 
class CTagsAutoComplete(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):
        if is_disabled_in(view.scope_name(locations[0])):
            return []
 
        results = []
 
        ctags_paths = [folder + '\.tags' for folder in view.window().folders()]
        ctags_rows  = []
 
        for ctags_path in ctags_paths:
            if not is_file_exist(view, ctags_path):
                return []
            ctags_path = str(ctags_path)
            ctags_file = open(ctags_path, encoding = 'utf-8')
            ctags_rows += ctags_file.readlines()
            ctags_file.close()
 
        for rows in ctags_rows:
            target = re.findall('^' + prefix + '.*', rows)
            if target:
                matched = re.split('\t', str(target[0]))
                trigger = matched[0]
                trigger += '\t(%s)' % 'CTags'
                contents = re.findall(prefix + '[0-9a-zA-Z_]*\(.*\)', str(matched[2]))
                if (len(matched) > 1 and contents):
                    results.append((trigger, contents[0]))
                    results = list(set(results))
                    results.sort()
 
        return (results, sublime.INHIBIT_WORD_COMPLETIONS | sublime.INHIBIT_EXPLICIT_COMPLETIONS)
 
def is_disabled_in(scope):
    excluded_scopes = settings.get("exclude_from_completion", [])
    for excluded_scope in excluded_scopes:
        if scope.find(excluded_scope) != -1:
            return True
    return False
 
def is_file_exist(view, file):
    if (not view.window().folders() or not os.path.exists(file)):
        return False
    return True
 
plugin_loaded()

之后我會把這個插件整合好后，上傳到 Package Control 上，從而方便更多人使用。通過這次入門，我嘗到了甜頭，未來的開發(fā)過程中，可能會出現(xiàn)各種各樣獨特的需求，如果已有的插件無法提供幫助，那就自己上吧。