- 作者: wsdjeg
- LICENSE: CC BY-SA 4.0.
Vim 插件开发中文指南,主要包括 Vim 脚本语法、插件开发技巧等。
在写脚本时,经常需要在源码里面添加一些注释信息,辅助阅读源码,Vim 脚本注释比较简单,是以 "
开头的,只存在行注释,不存在块注释。因此,对于多行注释,需要再每行开头添加 "
。
示例:
" 这是一行注释,
let g:helloworld = 1 " 这是在行尾注释
在 Vim 脚本里,可以使用关键字 let
来申明变量,最基本的方式为:
" 定义一个类型是字符串的变量 g:helloworld
let g:helloworl = "sss"
前面的例子中,是定义一个字符串,Vim 脚本中支持以下几种数据类型:
类型 | ID | 描述 |
---|---|---|
Number | 0 | 整数 |
String | 1 | 字符串 |
Funcref | 2 | 函数指针 |
List | 3 | 列表 |
Dictionary | 4 | 字典 |
Float | 5 | 浮点数 |
Boolean | 6 | |
None | 7 | |
Job | 8 | |
Channel | 9 |
Vim 变量存在三种作用域,全局变量、局部变量、和脚本变量。通常,我们以不同的前缀来区别作用域,比如使用 g:
表示全局变量,s:
表示脚本变量。
在一些特殊情况下,前缀是可以省略的,Vim 会为该变量选择默认的作用域。不同的情况下,默认的作用域是不一样的,在函数内部,默认作用域是局部变量,
而在函数外部,默认作用域是全局变量:
let g:helloworld = 1 " 这是一个全局变量, g: 前缀未省略
let helloworld = 1 " 这也是一个全局变量,在函数外部,默认的作用域是全局的
function! HelloWorld()
let g:helloworld = 1 " 这是函数内部全局变量
let helloworld = 1 " 这是一个函数内部的局部变量,在函数内部,默认的作用域为局部变量
endfunction
前缀 | 描述 |
---|---|
g: |
全局变量 |
l: |
局部变量,只可在函数内部使用 |
s: |
脚本变量,只可以在当前脚本函数内使用 |
v: |
Vim 特殊变量 |
b: |
作用域限定在某一个缓冲区内 |
w: |
作用域限定在窗口内部 |
t: |
作用域限定在标签内部 |
此外,在开发 Vim 插件之前,你还需要了解 vimrc 和 Vim 插件的区别。
在开发 Vim 插件之前,需要了解一下,一个 Vim 插件项目的目录结构是怎样的,以及每一个目录里文件的意义是什么。 Vim 插件标准的目录结构为:
autoload/ 自动载入脚本
colors/ 颜色主题
plugin/ 在 Vim 启动时将被载入的脚本
ftdetect/ 文件类型识别脚本
syntax/ 语法高亮文件
ftplugin/ 文件类型相关插件
compiler/ 编译器
indent/ 语法对齐
下面,我们来逐一说明下每一个目录的用途:
autoload/
顾名思义,该文件夹下的脚本会在特点条件下自动被载入。这里的特定条件指的是当某一个 autoload 类型的函数被调用,并且 Vim 当前环境下并未定义该函数时。
比如调用 call helloworld#init()
时,Vim 会先检测当前环境下是否定义了该函数,若没有,则在 autoload/
目录下找 helloworld.vim
这一文件,
并将其载入,载入完成后执行 call helloworld#init()
.
plugin/
该目录里的文件将在 Vim 启动时被运行,作为一个优秀的 Vim 插件,应当尽量该目录下的脚本内容。通常,可以将插件的快捷键、命令的定义保留在这个文件里。
ftdetect/
ftdetect 目录里通常存放的是文件类型检测脚本,该目录下的文件也是在 Vim 启动时被载入的。在这一目录里的文件内容,通常比较简单,比如:
autocmd BufNewFile,BufRead *.helloworld set filetype=helloworld
以上脚本使得 Vim 在打开以 .helloworld
为后缀的文件时,将文件类型设置为 helloworld
。通常,这个脚本的文件名是和所需要设置的文件类型一样的,上面的例子中文件的名称就是 helloworld.vim
。
syntax/
这一目录下的文件,主要是定义语法高亮的。通常文件名前缀和对应的语言类型相同,比如 Java 的语法文件文件名为 java.vim
。 关于如何写语法文件,将在后面详细介绍。
colors/
colors 目录下主要存储一些颜色主题脚本,当执行 :colorscheme + 主题名
命令时,对应的颜色主题脚本将被载入。比如执行 :colorscheme helloworld
时,colors/helloworld.vim
这一脚本将被载入。
compiler/
这一名录里是一些预设的编译器参数,主要给 :make
命令使用的。在最新版的 Vim 中可以使用 :compiler! 编译器名
来为当前缓冲区设定编译器。比如当执行
:compiler! helloworld
时,compiler/helloworld.vim
这一脚本将被载入。
indent/
在 indent 目录里,主要是一些语法对齐相关的脚本。
Vim 的自定义命令可以通过 command
命令来定义,比如:
command! -nargs=* -complete=custom,helloworld#complete HelloWorld call helloworld#test()
紧接 command
命令其后的 !
表示强制定义该命令,即使前面已经定义过了同样名称的命令,也将其覆盖掉。 -nargs=*
表示,该命令可接受任意个数的参数,
包括 0 个。-nargs
的取值有以下几种情况:
参数 | 定义 |
---|---|
-nargs=0 |
不接受任何参数(默认) |
-nagrs=1 |
只接受一个参数 |
-nargs=* |
可接收任意个数参数 |
-nargs=? |
可接受 1 个或者 0 个参数 |
-nargs=+ |
至少提供一个参数 |
-complete=custom,helloworld#complete
表示,改命令的补全方式采用的是自定义函数 helloworld#complete
。-complete
可以接受的参数包括如下内容:
参数 | 描述 |
---|---|
-complete=augroup |
autocmd 组名 |
-complete=buffer |
buffer 名称 |
-complete=behave |
:behave 命令子选项 |
-complete=color |
颜色主题 |
-complete=command |
Ex 命令及参数 |
-complete=compiler |
编译器 |
-complete=cscope |
:cscope 命令子选项 |
-complete=dir |
文件夹名称 |
-complete=environment |
环境变量名称 |
-complete=event |
自动命令的事件名称 |
-complete=expression |
Vim 表达式 |
-complete=file |
文件及文件夹名称 |
-complete=file_in_path |
path 选项里的文件及文件夹名称 |
-complete=filetype |
文件类型 |
-complete=function |
函数名称 |
-complete=help |
帮助命令子选项 |
-complete=highlight |
高亮组名称 |
-complete=history |
:history 子选项 |
-complete=locale |
locale 名称(相当于命令 locale -a 的输出) |
-complete=mapping |
快捷键名称 |
-complete=menu |
目录 |
-complete=messages |
:messages 命令子选项 |
-complete=option |
Vim 选项名称 |
-complete=packadd |
可选的插件名称补全 |
-complete=shellcmd |
shell 命令补全 |
-complete=sign |
:sign 命令补全 |
-complete=syntax |
语法文件名称补全 |
-complete=syntime |
:syntime 命令补全 |
-complete=tag |
tags |
-complete=tag_listfiles |
tags, file names are shown when CTRL-D is hit |
-complete=user |
user names |
-complete=var |
user variables |
-complete=custom,{func} |
custom completion, defined via {func} |
-complete=customlist,{func} |
custom completion, defined via {func} |
这里主要解释一些自定义的补全函数,从上面的表格可以看出,有两种定义自定义命令补全函数的方式。
-complete=custom,{func}
和 -complete=customlist,{func}
。这两种区别在与函数的返回值,
前者要求是一个 string
而后者要求补全函数的返回值是 list
.
自定义命令补全函数接受三个参数。
:function {func}(ArgLead, CmdLine, CursorPos)
我们以实际的例子来解释这三个参数的含义,比如在命令行是如下内容时,|
表示光标位置,我按下了 <Tab>
键调用了补全函数,那么传递给补全函数的三个参数分别是:
:HelloWorld hello|
参数名 | 描述 |
---|---|
ArgLead |
当前需要补全的部分,通常是光标前的字符串,上面的例子中是指 hello |
CmdLine |
指的是整个命令行内的内容,此时是 HelloWorld hello |
CursorPos |
指的当前光标所在的位置,此时是 16, 即为 len('HelloWorld hello') |
下面,我们来看下定义的函数具体内容:
function! helloworld#complete(ArgLead, CmdLine, CursorPos) abort
return join(['hellolily', 'hellojeky', 'hellofoo', 'world']
\ "\n")
endfunction
在上面的函数里,返回的实际上是一个有四行的字符串,Vim 会自动根据 ArgLead
来筛选出可以用来补全的选项,并展示在状态栏上。
此时,四行里最后一个 world
因为开头不匹配 ArgLead
所以不会被展示在状态栏上,因此补全效果只有三个可选项。
-complete=customlist,{func}
这一参数所对应的补全函数,也是接受相同的三个参数,但该函数返回的是一个 list。
下面,我们来测试这个函数:
function! helloworld#complete(ArgLead, CmdLine, CursorPos) abort
return ['hellolily', 'hellojeky', 'hellofoo', 'world']
endfunction
区别很明显,customlist
补全时不会自动根据 ArgLead
进行筛选,并且直接补全整个返回的 list,即使列表中有一个 world
完全与 ArgLead(hello)
不同,
也会将其直接覆盖。因此,当使用 customlist
时,需要在函数内根据 ArgLead
进行筛选,将函数该为如下,就可以得到相同效果了:
function! helloworld#complete(ArgLead, CmdLine, CursorPos) abort
return filter(['hellolily', 'hellojeky', 'hellofoo', 'world'], 'v:val =~ "^" . a:ArgLead')
endfunction
-bang
参数:
在定义 Vim 自定义命令时,可以通过 -bang
参数来申明这个命令接受感叹号。比如 :q
与 :q!
。
下面是一个实例:
fu! s:hello(bang)
if a:bang
echom "带有叹号"
else
echom "不带有叹号"
endif
endf
command! -bang Hello call s:hello(<bang>0)
在上面的实例里,函数的参数写法为 <bang>0
, 当执行:Hello!
时,传递给 s:hello
这一函数的参数是
!0
即为 1
,因此,此时看到打印了”带有叹号“。
其实除了写成 <bang>0
, 还可以写 <bang>1
, 甚至是 <bang>
+ 一个全局变量。比如:
let g:hello = 0
fu! s:hello(bang)
if a:bang
echom "带有叹号"
else
echom "不带有叹号"
endif
endf
command! -bang Hello call s:hello(<bang>g:hello)