Add code snippets for CLANG in VS Code

日誌：

1. 2018.07.16 VSCode 自 v1.25 起，開始支援佔位符轉換（placeholder transformations）了，其用於在進行佔位符跳轉時（1→2）對當前佔位符（1）適用正則替換。新特性聽起來和變數轉換很像，它們的區別在於佔位符轉換適用於佔位符，而變數轉換適用於變數。前者更靈活，後者更省心。本次更新即旨於介紹這個新特性，並再次對排版進行適應性調整；
2. 2018.05.13 VSCode 自 v1.20 起，開始支援更多變數，其用於讀取剪貼簿內容及插入當前日期。本次更新即旨於介紹這些新變數。此外，本次更新還移除了一些廢話，並對排版進行了微調；
3. 2017.10.11 VSCode 自 v1.17 起，其程式碼段引擎開始支援變數轉換（variable transformations）特性，變數的值可以經過格式化處理後，再插入預定的位置。這是一個很強大的特性。另外，也不知道從什麼時候開始，VSCode 開始支援 Choice 了。本次更新即旨於介紹這些新特性。

前記：今天試著用了下 Atom，發現 Atom 居然預裝了 CLANG 的 snippets，而且遠比 VSCode 的已有拓展「C/C++ Snippets」中的豐富！身為 VSCode 的死忠粉，我決定立馬把 Atom 的 C snippets 搬到 VSCode 上來。

既然你點開了這個頁面，那就說明要麼你不知道 VSCode 上已有拓展「C/C++ Snippets」，要麼你對這個拓展不甚滿意。對於後者，本文將為你介紹如何在 VSCode 上設定 snippets，併為你提供一套可以直接用的 C 語言 snippets。

1. snippet 簡介

snippet[ˈsnɪpɪt]，或者說「code snippet」，也即程式碼段，指的是能夠幫助輸入重複程式碼模式，比如迴圈或條件語句，的模板。通過 snippet ，我們僅僅輸入一小段字串，就可以在程式碼段引擎的幫助下，生成預定義的模板程式碼，接著我們還可以通過在預定義的游標位置之間跳轉，來快速補全模板。

當然，看圖更易懂。下圖將 aja 補全為 JQuery 的 ajax() 方法，並通過游標的跳轉，快速補全了待填鍵值對：

2. snippet 配置流程

• 進入 snippet 設定檔案，這裡提供了三種方法：
  
  • 通過快捷鍵「Ctrl + Shift + P」開啟命令視窗（All Command Window），輸入「snippet」，點選「首選項：配置使用者程式碼段片段」；
  • 點選介面最左側豎欄（也即活動欄）最下方的齒輪按鈕，在彈出來的選單中點選「使用者程式碼片段」；
  • 按下「Alt」鍵切換選單欄，通過檔案 > 首選項 > 使用者程式碼片段；
• 填寫 snippets

3. snippet 詳細介紹

3.1 引子

設定檔案頭部的一個塊註釋給出了設定 snippet 的格式，瞭解過「json」就不會對此感到奇怪。

 // Place your snippets for C here. Each snippet is defined under a snippet name and has a prefix, body and 
 // description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
 // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the 
 // same ids are connected.
 // Example:
 "Print to console": {
    "prefix": "log",,
    "body": [
        "console.log('$1');",
        "$2"
    ],
    "description": "Log output to console"
}

上例定義了一個名為「Print to console」的 snippet，其功能為：在輸入 log 並確認後，可將原文字替換為console.log('');。效果預覽如下：

3.2 語法結構

然而引子中只是最簡單的功能，而 VSCode 的程式碼段引擎所能做的遠不止這些。本文將以官方教程1為本，對其進行詳實地闡述。

snippet 由三部分組成：

1. prefix：字首，定義了 snippets 從 IntelliSense 中撥出的關鍵字;
2. body： 主體，即模板的主體內容，其中每個字串表示一行;
3. description：說明，會在 IntelliSense 候選欄中出現。未定義的情況下直接顯示物件名，上例中將會顯示 Print to console。

Snippet 的三個部分目前只有主體部分支援豐富的特性。接下來整篇文章都是拿來介紹主體部分的。主體部分的介紹將分為兩部分：較為直接的基礎用法，及結合正則表示式的高階用法。

3.3 Body - 基本用法

主體部分可以使用特殊語法結構，來控制游標和要插入的文字，其支援的基本結構如下：

• Tabstops：製表符

  用「Tabstops」可以讓編輯器的指標在 snippet 內跳轉。使用 $1，$2 等指定游標位置。這些數字指定了游標跳轉的順序。特別地，$0表示最終游標位置。相同序號的「Tabstops」被連結在一起，將會同步更新，比如下列用於生成標頭檔案封裝的 snippet 被替換到編輯器上時，游標就將同時出現在所有$1位置。

  "#ifndef $1"
  "#define $1"
  "#end // $1"

• Placeholders：佔位符

  「Placeholder」是帶有預設值的「Tabstops」，如${1：foo}。「placeholder」文字將被插入「Tabstops」位置，並在跳轉時被全選，以方便修改。佔位符還可以巢狀，例如${1:another ${2:placeholder}}。

  比如，結構體的 snippet 主體可以這樣寫：

  struct ${1:name_t} {\n\t$2\n};

  作為「Placeholder」的name_t一方面可以提供預設的結構名稱，另一方面可以作為輸入的提示。

• Choice：可選項

  「Choice」是提供可選值的「Placeholder」。其語法為一系列用逗號隔開，並最終被兩個豎線圈起來的列舉值，比如 ${1|one,two,three|}。當游標跳轉到該位置的時候，使用者將會被提供多個值（one 或 two 或 three）以供選擇。

• Variables：變數

  使用$name或${name:default}可以插入變數的值。當變數未賦值時（如），將插入其預設值或空字串。 當varibale未知（即，其名稱未定義）時，將插入變數的名稱，並將其轉換為「Placeholder」。可以使用的「Variable」如下：

  • TM_SELECTED_TEXT：當前選定的文字或空字串；
    注：選定後通過在命令視窗點選「插入程式碼片段」插入。
  • TM_CURRENT_LINE：當前行的內容；
  • TM_CURRENT_WORD：游標所處單詞或空字串
    注：所謂游標一般為文字輸入處那條閃來閃去的豎線，該項可定製。單詞使用 VSCode 選詞（Word Wrap）器選擇。你最好只用它選擇英文單詞，因為這個選擇器明顯沒有針對寬字元優化過，它甚至無法識別寬字元的標點符號。
  • TM_LINE_INDEX：行號（從零開始）；
  • TM_LINE_NUMBER：行號（從一開始）；
  • TM_FILENAME：當前文件的檔名；
  • TM_FILENAME_BASE：當前文件的檔名（不含字尾名）；
  • TM_DIRECTORY：當前文件所在目錄；
  • TM_FILEPATH：當前文件的完整檔案路徑；
  • CLIPBOARD：當前剪貼簿中內容。

  此外，還有一些用於插入當前時間的變數，這裡單獨列出：

  • CURRENT_YEAR: 當前年份；
  • CURRENT_YEAR_SHORT: 當前年份的後兩位；
  • CURRENT_MONTH: 格式化為兩位數字的當前月份，如 02；
  • CURRENT_MONTH_NAME: 當前月份的全稱，如 July；
  • CURRENT_MONTH_NAME_SHORT: 當前月份的簡稱，如 Jul；
  • CURRENT_DATE: 當天月份第幾天；
  • CURRENT_DAY_NAME: 當天周幾，如 Monday；
  • CURRENT_DAY_NAME_SHORT: 當天周幾的簡稱，如 Mon；
  • CURRENT_HOUR: 當前小時（24 小時制）；
  • CURRENT_MINUTE: 當前分鐘；
  • CURRENT_SECOND: 當前秒數。

  注：這些都是變數名，不是巨集，在實際使用的時要加上 $ 符。

3.4 Body - 高階語法

3.4.1 變數轉換

變數轉換可將變數的值格式化處理後插入預定的位置。

3.4.1.1 語法結構

我們可以通過 ${var_name/regular_expression/format_string/options} 插入格式化後的程式碼段。顯然，「variable transformations」由 4 部分構成：

1. var_name：變數名；
2. regular_expression：正則表示式；
3. format_string：格式串；
4. options：正則表示式匹配選項。

其中正則表示式的寫法和匹配選項部分不在本篇博文的講解範圍之內，具體內容請分別參考 javascript 有關 RegExp(pattern [, flags]) 建構函式中的 pattern 及 flags 引數項的說明2。

本文只對 format_string 部分進行詳細介紹。

3.4.1.2 format_string 部分

根據其 EBNF 正規化，我們可以知道 format_string 其實是 format 或 text 的線性組合：

• text：也即沒有任何作用的普通文字，你甚至可以使用漢字；
• format：格式串，分為 7 種：
  
  • $sn：表示插入匹配項；
  • ${sn}：同 $sn；
  • ${sn:/upcase} 或 ${sn:/downcase} 或 ${sn:/capitalize}：表示將匹配項變更為「所有字母均大寫/所有字母均小寫/首字母大寫其餘小寫」後，插入；
  • ${sn:+if}：表示當匹配成功時，並且捕捉括號捕捉特定序號的捕捉項成功時，在捕捉項位置插入「if」所述語句；
  • ${sn:?if:else}：表示當匹配成功，並且捕捉括號捕捉特定序號的捕捉項成功時，在捕捉項位置插入「if」所述語句；否則當匹配成功，但當捕捉括號捕捉特定序號的捕捉項失敗時，在捕捉項位置插入「else」所述語句；
  • ${sn:-else}：表示當匹配成功，但當捕捉括號捕捉特定序號的捕捉項失敗時，在捕捉項位置插入「else」所述語句；
  • ${sn:else}：同 ${sn:-else}。

format 的後三條理解起來可能比較困難。這裡我們以倒數第三條為例進行說明。假設我們有一個「make.c」檔案，我們有這麼一條 snippet: "body": "${TM_FILENAME/make.c(pp|\+\+)?/${1:?c++:clang}/}"。整個模式串匹配成功，但是捕捉括號捕捉字尾名中的 pp 或 ++ 失敗，因此判斷條件在捕捉括號的位置插入捕捉失敗時應插入的字串，也即「clang」。

注：

• 其中 sn 表示捕捉項的序號
• 其中 if 表示捕捉項捕捉成功時替換的文字
• 其中 else 表示捕捉項捕失敗時替換的文字

3.4.1.3 案例分析

下面筆者再介紹一個簡單的例子，幫助大家理解「variable transformations」。

假設有一個名為「make.c」的檔案中，並且我們已經定義如下 snippet。

"#ifndef HEADER … #define … #endif":{
"prefix": "defheader",
"body": "#ifndef ${1:${TM_FILENAME/(.*)\\.C$/${1:/upcase}_H/i}} \n#define $1 \n${2:header content}\n#endif\t// $1"
}

這段 snippet 將生成下圖所示程式碼：

其中最複雜的模式為：${1:${TM_FILENAME/(.*)\\.C$/${1:/upcase}_H/i}}，我們將之拆解為如下五部分：
1. ${1:...}：巢狀的 placeholder；
1. ${TM_FILENAM/.../.../.}：「variable transformations」中的「var_name」，表示帶字尾的檔名；
1. ${.../(.*)\\.C$/.../.}：「variable transformations」中的「regular_expression」，表示匹配任意以「.C」為字尾的字串；
1. ${.../.../${1:/upcase}_H/.}}：「variable transformations」中的「options」，表示將第一個捕捉項替換為大寫的，並新增「_H」的字尾；
1. ${.../.../.../i}：「variable transformations」中的「options」，表示無視大小寫。

3.4.2 佔位符轉換

3.4.2.1 語法結構

我們可以通過 ${int/regular_expression/format_string/options} 插入格式化後的程式碼段。顯然，與變數轉換，「placeholder transformations」也由 4 部分構成：

1. int：佔位符相應游標序號；
2. regular_expression：正則表示式；
3. format_string：格式串；
4. options：正則表示式匹配選項。

上述全部內容我們都在前文介紹過了，因此此處不做贅述。我們唯一需要關注的是轉換觸發的時機：佔位符轉換將在進行佔位符跳轉（假設 1→2）的時候自動適用到當前佔位符（1）。

3.4.2.2 案例分析

假設我們已經這樣的 Snippet：

"HelloWorld": {
  "prefix": "say_hello",
  "body": "${1} ${2} -> ${1/Hello/Hallo/} ${2/World/Welt/}"
}

那麼我們在兩個製表位同時鍵入 Hello 並跳轉的時候，第一個製表位依然保持 Hello 不變，而第二個製表位（佔位符）被替換為 Hallo。鍵入 Welt 亦然。效果圖：

3.5 語法定義

官網給出了 snippet 的 EBNF 正規化的正則文法，注意，作普通字元使用時，$ , } 和 \ 可使用 \（反斜槓）轉義。

any         ::= tabstop | placeholder | choice | variable | text
tabstop     ::= '$' int
                | '${' int '}'
                | '${' int  transform '}'
placeholder ::= '${' int ':' any '}'
choice      ::= '${' int '|' text (',' text)* '|}'
variable    ::= '$' var | '${' var '}'
                | '${' var ':' any '}'
                | '${' var transform '}'
transform   ::= '/' regex '/' (format | text)+ '/' options
format      ::= '$' int | '${' int '}'
                | '${' int ':' '/upcase' | '/downcase' | '/capitalize' '}'
                | '${' int ':+' if '}'
                | '${' int ':?' if ':' else '}'
                | '${' int ':-' else '}' | '${' int ':' else '}'
regex       ::= JavaScript Regular Expression value (ctor-string)
options     ::= JavaScript Regular Expression option (ctor-options)
var         ::= [_a-zA-Z] [_a-zA-Z0-9]*
int         ::= [0-9]+
text        ::= .*

4. 一些建議

預設情況下 snippet 在 IntelliSense 中的顯示優先順序並不高，而且在 IntelliSense 中選擇相應 snippet 需要按「enter」鍵，這對於手指短的人來說並不是什麼很好的體驗。

所幸，VSCode 意識到了這一點，併為我們提供了改進的方式。我們可以在 VSCode 的使用者設定（「Ctrl+P」在輸入框中寫「user settings」後點選）中，檢索程式碼段，然後根據提示修改程式碼段的相關設定。

我們可以設定在 IntelliSense 中優先顯示程式碼段，並可以通過「TAB」補全。

修改後設定檔案中會多出這兩行：

"editor.snippetSuggestions": "top",
"editor.tabCompletion": true

附錄

說好的附錄。

另，我對 Atom 的 C snippet3 作了部分修改，使之更適合我的習慣，若有興致你可自行修改，反正也不難。

{
/*
     // Place your snippets for C here. Each snippet is defined under a snippet name and has a prefix, body and 
     // description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
     // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the 
     // same ids are connected.
     // Example:
     "Print to console": {
        "prefix": "log",,
        "body": [
            "console.log('$1');",
            "$2"
        ],
        "description": "Log output to console"
    }
*/
  "#ifndef … #define … #endif":{
    "prefix": "def",
    "body": "#ifndef ${1:SYMBOL}\n#define $1 ${2:value}\n#endif\t// ${1:SYMBOL}"
  },
  "#include <>":{
    "prefix": "Inc",
    "body": "#include <${1:.h}>"
  },
  "#include \"\"":{
    "prefix": "inc",
    "body": "#include \"${1:.h}\""
  },
  "#pragma mark":{
    "prefix": "mark",
    "body": "#if 0\n${1:#pragma mark -\n}#pragma mark $2\n#endif\n\n$0"
  },
  "main()":{
    "prefix": "main",
    "body": "int main(int argc, char const *argv[]) {\n\t$1\n\treturn 0;\n}"
  },
  "For Loop":{
    "prefix": "for",
    "body": "for (${1:i} = 0; ${1:i} < ${2:count}; ${1:i}${3:++}) {\n\t$4\n}"
  },
  "Define and For Loop":{
    "prefix": "dfor",
    "body": "size_t ${1:i};\nfor (${1:i} = ${2:0}; ${1:i} < ${3:count}; ${1:i}${4:++}) {\n\t$5\n}"
  },

  "Header Include-Guard":{
    "prefix": "once",
    "body": "#ifndef ${1:SYMBOL}\n#define $1\n\n${2}\n\n#endif /* end of include guard: $1 */\n"
  },
  "Typedef":{
    "prefix": "td",
    "body": "typedef ${1:int} ${2:MyCustomType};"
  },
  "Typedef Struct":{
    "prefix": "tst",
    "body": "typedef struct ${1:StructName} {\n\t$2\n}${3:MyCustomType};"
  },
  "Do While Loop":{
    "prefix": "do",
    "body": "do {\n\t$0\n} while($1);"
  },
  "While Loop":{
    "prefix": "while",
    "body": "while ($1) {\n\t$2\n}"
  },
  "fprintf":{
    "prefix": "fprintf",
    "body": "fprintf(${1:stderr}, \"${2:%s}\\\\n\", $3);$4"
  },
  "If Condition":{
    "prefix": "if",
    "body": "if ($1) {\n\t$2\n}"
  },
  "If Else":{
    "prefix": "ife",
    "body": "if ($1) {\n\t$2\n} else {\n\t$3\n}"
  },
  "If ElseIf":{
    "prefix": "iff",
    "body": "if ($1) {\n\t$2\n} else if ($3) {\n\t$4\n}"
  },
  "If ElseIf Else":{
    "prefix": "iffe",
    "body": "if ($1) {\n\t$2\n} else if ($3) {\n\t$4\n} else {\n\t$5\n}"
  },
  "Switch Statement":{
    "prefix": "sw",
    "body": "switch ($1) {\n$2default:\n\t${3:break;}\n}$0"
  },
  "case break":{
    "prefix": "cs",
    "body": "case $1:\n\t$2\n\tbreak;\n$0"
  },
  "printf":{
    "prefix": "printf",
    "body": "printf(\"${1:%s }\\n\", $2);$3"
  },
  "scanf":{
    "prefix": "scanf",
    "body": "scanf(\"${1:%s}\\n\", $2);$3"
  },
  "Struct":{
    "prefix": "st",
    "body": "struct ${1:name_t} {\n\t$2\n};"
  },
  "void":{
    "prefix": "void",
    "body": "void ${1:name}($2) {\n\t$3\n}"
  },
  "any function":{
    "prefix": "func",
    "body": "${1:int} ${2:name}($3) {\n\t$5\n\treturn ${4:0};\n}"
  },
  "write file":{
    "prefix": "wf",
    "body": "FILE *${1:fp};\n${1:fp} = fopen (\"${2:filename.txt}\",\"w\");\nif (${1:fp}!=NULL)\n{\n\tfprintf(${1:fp},\"${3:Some String\\\\n}\");\n\tfclose (${1:fp});\n}"
  },
  "read file":{
    "prefix": "rf",
    "body": "FILE *${1:fp};\n${1:fp} = fopen (\"${2:filename.txt}\",\"r\");\nif (${1:fp}!=NULL)\n{\n\tfscanf(${1:fp},\"${3:Some String\\\\n}\", ${3:&var});\n\tfclose (${1:fp});\n}",
    "description": "read file opeartion including fopen, fscanf and fclose."
  }
}