• 简介
• 基本语法
  • 注释
  • 变量
  • 作用域
  • 函数定义
• 插件的目录结构
• Vim 自定义命令

简介

(Neo)Vim 插件开发中文指南，主要包括 Vim 脚本语法、插件开发技巧等。

基本语法

注释

在写脚本时，经常需要在源码里面添加一些注释信息，辅助阅读源码，Vim 脚本注释比较简单，是以 " 开头的，只存在行注释，不存在块注释。因此，对于多行注释，需要再每行开头添加 "。

示例：

" 这是一行注释，
let g:helloworld = 1  " 这是在行尾注释

变量

在 Vim 脚本里，可以使用关键字 let 来申明变量，最基本的方式为：

" 定义一个类型是字符串的变量 g:helloworld
let g:helloworl = "sss"

前面的例子中，是定义一个字符串，Vim 脚本中支持以下几种数据类型：

作用域

Vim 变量存在三种作用域，全局变量、局部变量、和脚本变量。通常，我们以不同的前缀来区别作用域，比如使用 g: 表示全局变量，s: 表示脚本变量。 在一些特殊情况下，前缀是可以省略的，Vim 会为该变量选择默认的作用域。不同的情况下，默认的作用域是不一样的，在函数内部，默认作用域是局部变量， 而在函数外部，默认作用域是全局变量：

let g:helloworld = 1  " 这是一个全局变量， g: 前缀未省略
let helloworld = 1    " 这也是一个全局变量，在函数外部，默认的作用域是全局的

function! HelloWorld()
  let g:helloworld = 1    " 这是函数内部全局变量
  let helloworld = 1      " 这是一个函数内部的局部变量，在函数内部，默认的作用域为局部变量
endfunction

此外，在开发 Vim 插件之前，你还需要了解 vimrc 和 Vim 插件的区别。

函数定义

可以使用 function 关键字定义函数，可缩写成 func 或者 fn, 格式：

:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]

当使用了参数 closure 时，函数可以访问外部的变量或者参数，比如：

function! Foo()
  let x = 0
  function! Bar() closure
    let x += 1
    return 1
  endfunction
  return funcref('Bar')
endfunction

let F = Foo()

echo F()
" 1
echo F()
" 2
echo F()
" 3

插件的目录结构

在开发插件之前，需要了解下一个插件项目的目录结构是怎样的，以及每一个目录里文件的意义是什么。

插件标准的目录结构为：

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 自定义命令

Vim 的自定义命令可以通过 command 命令来定义，比如：

command! -nargs=* -complete=custom,helloworld#complete HelloWorld call helloworld#test()

紧接 command 命令其后的 ! 表示强制定义该命令，即使前面已经定义过了同样名称的命令，也将其覆盖掉。 -nargs=* 表示，该命令可接受任意个数的参数， 包括 0 个。-nargs 的取值有以下几种情况：

-complete=custom,helloworld#complete 表示，改命令的补全方式采用的是自定义函数 helloworld#complete。-complete 可以接受的参数包括如下内容：

这里主要解释一些自定义的补全函数，从上面的表格可以看出，有两种定义自定义命令补全函数的方式。 -complete=custom,{func} 和 -complete=customlist,{func}。这两种区别在与函数的返回值， 前者要求是一个 string 而后者要求补全函数的返回值是 list. 自定义命令补全函数接受三个参数。

:function {func}(ArgLead, CmdLine, CursorPos)

我们以实际的例子来解释这三个参数的含义，比如在命令行是如下内容时，| 表示光标位置，我按下了 <Tab> 键调用了补全函数，那么传递给补全函数的三个参数分别是：

: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)

• 设置 SpaceVim 选项
• 启用/禁用   模块
• 添加自定义插件
• 自定义快捷键及插件配置

本文将系统地介绍如何配置 SpaceVim，配置  SpaceVim  主要包括以下几个内容：

• 设置  SpaceVim  选项
• 启动/禁用模块
• 添加自定义插件
• 添加自定义按键映射以及插件配置

设置 SpaceVim 选项

原先，在老版本的 SpaceVim 中，默认的配置文件是 init.vim。在  init.vim  文件内，我们可以通过  let g:spacevim_* 这样的语句来设置 SpaceVim 选项。而在新版的  SpaceVim  中，我们采用了  toml  作为默认配置文件，如果不熟悉  toml  语法的，可以先阅读一下  toml  的基本语法，当然不读也没关系， toml  已经是最简单的配置文件格式了。 所有的  SpaceVim  选项配置在一个字典里，key  为原先的选项名去除  g:spacevim_ 前缀：

g:spacevim_enable_guicolors -> enable_guicolors

这一选项的值可为  true  或者  false，于是，写入配置即为：

[options]
    enable_guicolors = false

一些其他选项，有的值是数字，有的是字符串，字符串的格式和  vim script  类似，可以用单引号，也可以用双引号，比如：

[options]
    enable_guicolors = false
    snippet_engine = "neosnippet"
    statusline_separator = 'arrow'
    sidebar_width = 30

启用/禁用   模块

SpaceVim  内置了很多模块，每一个模块由一些插件和相关配置组成，用于提供一些特定的功能，比如提供模糊搜索的模块， 提供版本控制的模块，以及提供语言开发支持的语言模块。 启用或者禁用模块，需要遵循一定的语法结构，并且配到  layers  列表内，比如我现在需要启用  shell  模块，设置模块选项 default_position  和  default_height,  这两个选项分别控制这  shell  窗口打开位置和高度：

[[layers]]
    name = "shell"
    default_position = "top"
    default_height = 30

如果要禁用一个模块，需要增添一个选项  enable,  并赋值  false，默认这个是  true。比如，我需要禁用  shell  模块， 可以这么写,  禁用模块时，除了  enable  这选项，其他选项可写可不写，因为已经不会生效。当然如果为了快速启用/禁用模块， 可以保持其他选项不变。

[[layers]]
    name = "shell"
    enable = false

添加自定义插件

自定义插件配置语法和模块有点类似，将需要配置的插件，配置进  custom_plugins  列表。比如，我需要添加  2  个插件， 可以参考以下语法：

[[custom_plugins]]
    name = "lilydjwg/colorizer"
    merged = 0

[[custom_plugins]]
    name = "tpope/vim-scriptease"
    merged = 0
    on_cmd = "Scriptnames"

大家可以看到，在添加自定义插件时，我们支持很多选项，这归功于 dein, dein  支持多种选项。

自定义快捷键及插件配置

最后，我们来说下，如果添加自定义配置，和自定义快捷键。在使用  toml  配置  SpaceVim  时，我们提供了两个选项，位于  [options]  下： bootstrap_before  和  bootstrap_after,  这两个选项接受一个字符串最为值，该字符串值得是一个  vim  方法名。顾名思义，你可以通过这 两个选项定义两个  vim  方法，分别在载入配置时，和  vim  启动后被调用，在方法内，你可以加入一些  vim  脚本，比如快捷键， 比如插件的选项。 比如，在配置文件内加入如下内容：

[options]
    enable_guicolors = false
    snippet_engine = "neosnippet"
    statusline_separator = 'arrow'
    sidebar_width = 30
    bootstrap_before = "myspacevim#before"
    bootstrap_after = "myspacevim#after"

新建  ~/.SpaceVim.d/autoload/myspacevim.vim,  加入内容：

function! myspacevim#before() abort
    let g:neomake_enabled_c_makers = ['clang']
    nnoremap jk <esc>
endf
function! myspacevim#after() abort
endf

在上述这个方法内部，目前只定义了一个变量和快捷键，用户可以添加一些其他的 vim 脚本，比如定制一些 autocmd

augroup MySpaceVim
  au!
  autocmd FileType markdown setlocal nowrap
augroup END

也是应大多数人要求，更新的这篇文字，仓促之下，有很多内容可能还不完整，如果有什么疑问，欢迎留言。

• 数值类型(Number)

Ruby支持的数据类型包括基本的Number、String、Ranges、Symbols，以及true、false和nil这几个特殊值，同时还有两种重要的数据结构——Array和Hash。

数值类型(Number)

1、整型(Integer)

整型分两种，如果在31位以内（四字节），那为Fixnum实例。如果超过，即为Bignum实例。

整数范围从 -230 到 230-1 或 -262 到 262-1。在这个范围内的整数是类 Fixnum 的对象，在这个范围外的整数存储在类 Bignum 的对象中。

您可以在整数前使用一个可选的前导符号，一个可选的基础指标（0 对应 octal，0x 对应 hex，0b 对应 binary），后跟一串数字。下划线字符在数字字符串中被忽略。

您可以获取一个 ASCII 字符或一个用问号标记的转义序列的整数值。

实例

123                  # Fixnum 十进制
1_234                # Fixnum 带有下划线的十进制
-500                 # 负的 Fixnum
0377                 # 八进制
0xff                 # 十六进制
0b1011               # 二进制
?a                   # 'a' 的字符编码
?\n                  # 换行符（0x0a）的编码
12345678901234567890 # Bignum

#整型 Integer 以下是一些整型字面量 
#字面量（literal）：代码中能见到的值，数值，bool值，字符串等都叫字面量 
#如以下的0,1_000_000,0xa等 
a1=0 

#带千分符的整型 
a2=1_000_000 

#其它进制的表示 
a3=0xa 
puts a1,a2 
puts a3 

#puts print 都是向控制台打印字符，其中puts带回车换行符 
=begin 
这是注释，称作：嵌入式文档注释 
类似C#中的/**/ 
=end 

浮点型

Ruby 支持浮点数。它们是带有小数的数字。浮点数是类 Float 的对象，且可以是下列中任意一个。

实例

123.4                # 浮点值
1.0e6                # 科学记数法
4E20                 # 不是必需的
4e+20                # 指数前的符号

#浮点型 
f1=0.0 
f2=2.1 
f3=1000000.1 
puts f3  

算术操作

加减乘除操作符：+-*/；指数操作符为**

指数不必是整数，例如

#指数算术 
puts 2**(1/4)#1与4的商为0，然后2的0次方为1 
puts 16**(1/4.0)#1与4.0的商为0.25（四分之一），然后开四次方根 

字符串类型

Ruby 字符串简单地说是一个 8 位字节序列，它们是类 String 的对象。

双引号标记的字符串允许替换和使用反斜线符号，单引号标记的字符串不允许替换，且只允许使用 \\ 和 \' 两个反斜线符号。

实例

#!/usr/bin/ruby -w

puts 'escape using "\\"';
puts 'That\'s right';

实例

#!/usr/bin/ruby -w

puts 'escape using "\\"';
puts 'That\'s right';

这将产生以下结果：

escape using "\"
That's right

您可以使用序列 #{ expr } 替换任意 Ruby 表达式的值为一个字符串。在这里，expr 可以是任意的 Ruby 表达式。

#!/usr/bin/ruby -w

puts "Multiplication Value : #{24*60*60}";

这将产生以下结果：

Multiplication Value : 86400

#!/usr/bin/ruby -w

name="Ruby" 
puts name 
puts "#{name+",ok"}" 

输出结果为：

Ruby
Ruby,ok

反斜线符号

下表列出了 Ruby 支持的反斜线符号：

如需了解更多有关 Ruby 字符串的细节，请查看 Ruby 字符串（String）。

数组

数组字面量通过[]中以逗号分隔定义，且支持range定义。

（1）数组通过[]索引访问 （2）通过赋值操作插入、删除、替换元素 （3）通过+，－号进行合并和删除元素，且集合做为新集合出现 （4）通过«号向原数据追加元素 （5）通过*号重复数组元素 （6）通过｜和&符号做并集和交集操作（注意顺序）

实例

#!/usr/bin/ruby
ary = [ "fred", 10, 3.14, "This is a string", "last element", ]
ary.each do |i|
    puts i
end

运行实例 »

这将产生以下结果：

fred
10
3.14
This is a string
last element

如需了解更多有关 Ruby 数组的细节，请查看 Ruby 数组（Array）。

哈希类型

Ruby 哈希是在大括号内放置一系列键/值对，键和值之间使用逗号和序列 => 分隔。尾部的逗号会被忽略。

实例

#!/usr/bin/ruby

hsh = colors = { "red" => 0xf00, "green" => 0x0f0, "blue" => 0x00f }
hsh.each do |key, value|
    print key, " is ", value, "\n"
end

运行实例 »

这将产生以下结果：

green is 240
red is 3840
blue is 15

如需了解更多有关 Ruby 哈希的细节，请查看 Ruby 哈希（Hash）。

范围类型

一个范围表示一个区间。 范围是通过设置一个开始值和一个结束值来表示。范围可使用 s..e 和 s…e 来构造，或者通过 Range.new 来构造。

使用 .. 构造的范围从开始值运行到结束值（包含结束值）。使用 … 构造的范围从开始值运行到结束值（不包含结束值）。当作为一个迭代器使用时，范围会返回序列中的每个值。

范围 (1..5) 意味着它包含值 1, 2, 3, 4, 5，范围 (1…5) 意味着它包含值 1, 2, 3, 4 。

实例

#!/usr/bin/ruby

(10..15).each do |n|
    print n, ' '
end

这将产生以下结果：

10 11 12 13 14 15

• 程序中的空白
• 程序中的行尾
• 标识符
• 保留字
• Here Document
• BEGIN 语句
• END 语句
• 注释

让我们编写一个简单的 Ruby 程序。所有的 Ruby 文件扩展名都是 .rb。所以，把下面的源代码放在 test.rb 文件中。 实例

#!/usr/bin/ruby -w
puts "Hello, Ruby!";

在这里，假设您的 /usr/bin 目录下已经有可用的 Ruby 解释器。现在，尝试运行这个程序，如下所示：

$ ruby test.rb

这将会产生下面的结果：

Hello, Ruby!

您已经看到了一个简单的 Ruby 程序，现在让我们看看一些 Ruby 语法相关的基本概念：

程序中的空白

在 Ruby 代码中的空白字符，如空格和制表符一般会被忽略，除非当它们出现在字符串中时才不会被忽略。然而，有时候它们用于解释模棱两可的语句。当启用 -w 选项时，这种解释会产生警告。

实例：

a + b 被解释为 a+b （这是一个局部变量）
a  +b 被解释为 a(+b) （这是一个方法调用）

程序中的行尾

Ruby 把分号和换行符解释为语句的结尾。但是，如果 Ruby 在行尾遇到运算符，比如 +、- 或反斜杠，它们表示一个语句的延续。

标识符

标识符是变量、常量和方法的名称。Ruby 标识符是大小写敏感的。这意味着 Ram 和 RAM 在 Ruby 中是两个不同的标识符。

Ruby 标识符的名称可以包含字母、数字和下划线字符（ _ ）。

保留字

下表列出了 Ruby 中的保留字。这些保留字不能作为常量或变量的名称。但是，它们可以作为方法名。

BEGIN	do	next	then
END	else	nil	true
alias	elsif	not	undef
and	end	or	unless
begin	ensure	redo	until
break	false	rescue	when
case	for	retry	while
class	if	return	while
def	in	self	__FILE__
defined?	module	super	__LINE__

Here Document

“Here Document” 是指建立多行字符串。在 « 之后，您可以指定一个字符串或标识符来终止字符串，且当前行之后直到终止符为止的所有行是字符串的值。

如果终止符用引号括起，引号的类型决定了面向行的字符串类型。请注意« 和终止符之间必须没有空格。

下面是不同的实例：

#!/usr/bin/ruby -w
# -*- coding : utf-8 -*-

print <<EOF
    这是第一种方式创建here document 。
    多行字符串。
EOF

print <<"EOF";                # 与上面相同
    这是第二种方式创建here document 。
    多行字符串。
EOF

print <<`EOC`                 # 执行命令
	echo hi there
	echo lo there
EOC

print <<"foo", <<"bar"	      # 您可以把它们进行堆叠
	I said foo.
foo
	I said bar.
bar

这将产生以下结果：

    This is the first way of creating
    her document ie. multiple line string.
    This is the second way of creating
    her document ie. multiple line string.
hi there
lo there
        I said foo.
        I said bar.

BEGIN 语句

语法

BEGIN {
   code
}

声明 code 会在程序运行之前被调用。

实例

#!/usr/bin/ruby

puts "This is main Ruby Program"

BEGIN {
   puts "Initializing Ruby Program"
}

这将产生以下结果：

Initializing Ruby Program
This is main Ruby Program

END 语句

语法

END {
   code
}

声明 code 会在程序的结尾被调用。

实例

#!/usr/bin/ruby

puts "This is main Ruby Program"

END {
   puts "Terminating Ruby Program"
}
BEGIN {
   puts "Initializing Ruby Program"
}

这将产生以下结果：

Initializing Ruby Program
This is main Ruby Program
Terminating Ruby Program

注释

注释会对 Ruby 解释器隐藏一行，或者一行的一部分，或者若干行。您可以在行首使用字符（ # ）：

# 我是注释，请忽略我。

或者，注释可以跟着语句或表达式的同一行的后面：

name = "Madisetti" # 这也是注释

您可以注释多行，如下所示：

# 这是注释。
# 这也是注释。
# 这也是注释。
# 这还是注释。

下面是另一种形式。这种块注释会对解释器隐藏 =begin/=end 之间的行：

=begin
这是注释。
这也是注释。
这也是注释。
这还是注释。
=end

一直想再多接触一些脚本语言，之前写了一段时间 python 和 lua，感觉都非常不错。之所以要再学习 Ruby， 主要是看到 Ruby 的一些语法上的灵活性。

Ruby 支持代码块、修饰符等这些在其他语言里似乎都没有，最简单的示例：

#!/usr/bin/ruby

$debug=1
puts "debug\n" if $debug

新建了一个 Ruby 的笔记仓库，用来记录 Ruby 学习资料。

https://github.com/wsdjeg/ruby-tutorial-cn

• 初心
• 使用说明
• 协作开发

初心

经常使用 markdown 进行中文写作，包括但不限于写一些文档。对于中文排版目前没有非常好的检查工具。 因此做了 chinese_linter.vim 这个插件，目的在于提示中文文档中一些常见的排版错误。

使用说明

在编辑中文文档时，使用如下命令即可检查，错误信息将被展示在 Vim 的 location list 窗口

:CheckChinese

目前支持如下错误代码：

该插件才开始做，目前仅仅实现了以上五种规范检查，后面会添加更多的规范检查，欢迎尝试。

协作开发

目前这个项目发布在 github 上面，如果有熟悉 Vim 脚本的同学，也欢迎参与，感谢！

wsdjeg/ChineseLinter.vim