map.cnx

Vim 中文文档

并且 ^[ is <Esc>)

你输入:   ab esc ^V^V^V^V^V^[

	所有的键盘输入都遵从 ^V 引用解释, 所以第一个, 第三个, 和第五个
	^V  字符只是为了允许把第二个, 和第四个  ^V 和 ^[ 输入到命令行里.

你看到:    ab esc ^V^V^[

	命令行里在 ^[ 之前包含两个实际的 ^V.  如果你采用这种方法, 这是
	它应该出现在你的 .exrc 文件的样子. 第一个 ^V 作为它自己引用的字符,
	所以你能在缩写中包含被引用的空白字符或 | 字符. :ab 命令对 ^[ 字符
	并不做特殊的事情, 所以不需要被引用. (尽管引用是无害的; 这就是输入7个
	[而不是 8 个!] ^V 会工作的原因.)

被保存为:  esc     ^V^[

	解析后, 该缩写的简短形式 ("esc") 和扩展形式 (两字符 "^V^[") 被保存
	在缩写表中. 如果输入不带参数的 :ab 命令, 这是该缩写被显示的形式.

	然后当用户输入单词 "esc" 而该缩写被扩展时, 扩展形式服从和键盘输入
	同样形式的 ^V 解释. 所以 ^V 保护 ^[ 字符不被解释为 "退出输入模式"
	的字符, 而是把 ^[ 插入到文本里面.

扩展为: ^[

[example given by Steve Kirkendall]

==============================================================================
3. 局部映射和函数				*script-local*

当使用多个 Vim 脚本文件时, 一个脚本和另一个脚本使用同样名字的映射和函数是危险
的. 为了避免这种情况, 它们可以被局部在脚本中.

						*<SID>* *<SNR>* *E81*
字串 "<SID>" 能被用于一个映射或菜单中.  这要求 'cpoptions' 中没有
'<' 标志.
   当执行映射命令时, Vim 将把 "<SID>" 替换成特殊的键码 <SNR>, 后跟一个每个脚
本唯一的数字编号, 和一个下划线. 例如:
	:map <SID>Add
会定义一个映射 "<SNR>23_Add".

当在一个脚本中定义一个函数的时候, 可以在名字的前面用一个 "s:" 来使它局部于脚
本中. 但当一个映射从脚本外面被执行时, 它不知道该函数在哪个脚本中被定义. 为了
避免这种情况, 使用 "<SID>" 来代替 "s:". 它会做和映射一样的转换. 这使得在映射
里可以定义一个函数调用.

当一个局部函数被执行时, 它在定义他的脚本的上下文中运行. 这意味着, 它定义的新
的函数和映射也可以使用  "s:" 或 "<SID>" 并且当函数自己被定义时它也会使用同样
唯一的数字编码. 此外, 能使用 "s:var" 脚本局部变量.

当执行一个自动命令或一个用户命令时, 它将在定义它的脚本的上下文中运行. 这使得
该命令可以调用一个局部函数或者使用一个局部映射.

此外, 在一个脚本上下文之外使用 "<SID>" 是错误的.

如果你需要在一个复杂的脚本中取得脚本的数字编号, 可以使用这样的技巧:
	:map <SID>xx <SID>xx
	:let s:sid = maparg("<SID>xx")
	:unmap <SID>xx
然后删除尾部的 "xx".

当列表函数和映射时 "<SNR>" 会被显示.  要找出它们在哪里被定义时有用.

命令 |:scriptnames| 可以用来查看哪些脚本已经被读入以及它们的 <SNR> 数字编号.

这些都 {not in Vi} 并且 {not available when compiled without the +eval
feature}.

==============================================================================
4. 用户定义的命令				*user-commands*

可以定义你自己的 Ex 命令. 一个用户定义命令可以和内建命令一样运行 (他可以有一个
类型或参数, 参数可以是自动完成的文件名或缓冲名, 等等), 除了当这些命令被执行的时候,
会被转换成一个普通的 ex 命令然后再被执行.

对于初学者来说: 参考用户手册中的 |40.2| .

						*E183* *user-cmd-ambiguous*
所有用户定义的命令都必需以一个大写字母开头, 来避免与内建命令的冲突. (要注意
的是, 有一些内建命令比如 :Next, :Print and :X, 也以大写字母开头.  在这些情况
下内建的命令总是优先执行的). 用户命令的其它字符可以是大写字母, 小写字母或数字.
当使用数字时, 小心会和其它以数字作为参数的命令混淆. 例如, 命令 ":Cc2" 可能是
不带参数的用户命令 ":Cc2", 也可能是参数为 "2" 的命令 "Cc". 建议在命令名和参数
之间放置一个空格来避免这些问题.

当使用一个用户定义的命令时, 该命令可以是缩写. 但是, 如果一个缩写不唯一, 会发生
错误. 此外, 一个内建命令将总是被优先执行.

例如: >
	:command Rename ...
	:command Renumber ...
	:Rena				" Means "Rename"
	:Renu				" Means "Renumber"
	:Ren				" Error - ambiguous
	:command Paste ...
	:P				" The built-in :Print

建议在脚本中使用用户定义命令的全名.

:com[mand]						*:com* *:command*
			列出所有用户定义命令. 在列出命令时,
			前两栏的字符表示
			    !	命令有 -bang 属性
			    "	命令有 -register 属性
			    b	命令局部于当前缓冲
			(下面有属性的详细描述)

:com[mand] {cmd}	列出以 {cmd} 开头的用户命令

							*E174* *E182*
:com[mand][!] [{attr}...] {cmd} {rep}
			定义一个用户命令.  命令的名字是
			{cmd} 并且它替换的文本是 {rep}. 该命令的属性
			(参考下面)是 {attr}. 如果该命令已存在, 会报告错误,
			 除非已经指定了一个 !, 这种情况下命令被重定义.

:delc[ommand] {cmd}				*:delc* *:delcommand* *E184*
			删除用户定义命令 {cmd}.

:comc[lear]						*:comc* *:comclear*
			删除所有用户定义命令.

命令属性

Vim 和任何其它 ex 命令一样对待用户定义命令. 它能有参数, 或者指定一个类别.
以文件名, 缓冲等等作为参数. 它怎样工作完全取决于命令的属性, 属性在命令被
定义时被指定.

有很多种属性, 分为四大类: 参数处理, 填充行为, 范围处理, 和特殊情况.
属性在下面分类描述.

参数处理					*E175* *E176*

缺省时, 一个用户定义的命令将不接受参数 (如果使用了任何参数会报错).
但是指定命令可以接受参数是可能的, 使用 -nargs 属性, 有效的情况有:

	-nargs=0    不允许有参数 (缺省情况)
	-nargs=1    要求一个参数.
	-nargs=*    允许任何数目的参数 (0, 1, or many)
	-nargs=?    允许 0 或 1 个参数
	-nargs=+    必需给出参数, 但是数目任意

在这个上下文里, 参数被认为是以空格或Tab来分隔的.

自动完成行为				*:command-completion*
							*E179* *E180* *E181*
缺省时, 用户定义命令的参数不进行自动完成. 但是, 通过指定以下的一个或多个属性
后, 参数可以进行自动完成

	-complete=augroup	autocmd 组
	-complete=buffer	缓冲名
	-complete=command	Ex 命令 (及其参数)
	-complete=dir		目录名
	-complete=environment	环境变量名
	-complete=event		autocommand 事件
	-complete=expression	Vim 表达式
	-complete=file		文件和目录名
	-complete=function	函数名
	-complete=help		帮助主题
	-complete=highlight	高亮显示的部分
	-complete=mapping	映射名
	-complete=menu		菜单
	-complete=option	选项
	-complete=tag		标签
	-complete=tag_listfiles	当敲入 CTRL-D 时显示的标签, 文件名
	-complete=var		用户变量
	-complete=custom,{func} 用户自定制的自动完成, 通过 {func} 来定义

用户定制的自动完成			    *:command-completion-custom*
							*E467* *E468*
通过 "custom,{func}" 自动完成参数可以定义定制的自动完成方案. 其中 {func} 是有
如下原型的函数:

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

该函数不需要使用所有的这些参数, 但是应该提供自动完成候选作为返回值, 每行一个字
串用换行符分隔. 该函数的参数是:
	ArgLead		当前自动完成的前导参数
	CmdLine		完整的命令行
	CursorPos	里面的光标位置
该函数可能要根据这些来判别上下文. 它不必要来过滤对应 ArgLead (里面的隐式规
则) 的候选. 在函数返回时 Vim 将用它的正则表达式引擎来进行过滤, 这种方式在
大多数情况下效率更高.

以下的例子为一个 Finger 命令列出用户名 >
    :com -complete=custom,ListUsers -nargs=1 Finger !finger <args>
    :fun ListUsers(A,L,P)
    :    return system("cut -d: -f1 /etc/passwd")
    :endfun

范围处理						*E177* *E178*

缺省时, 用户定义的命令不接受一个行号范围. 但是, 也可以指定命令能够接受
一个范围 (-range 熟悉), 或者接受一个任意的数量值, 可以是行号位置
(-range=N, 与 |:split| 命令类似) 或者作为一个 "数量" 参数
(-count=N, 与 |:Next| 命令类似). 可能的属性有:

	-range	    允许使用范围, 缺省为当前行
	-range=%    允许使用范围, 缺省是整个文件 (1,$)
	-range=N    一个数量 (缺省是 N) 用来指定行号位置 (与 |:split|类似)
	-count=N    一个数量 (缺省是 N) 用来指定行号位置, 或者是作为一个初始
		    参数 (与 |:Next| 类似) 指定一个 -count (不设缺省值) 和
		    -count=0 一样

注意 -range=N 和 -count=N 是互斥的 - 只应该指定其中的一个.

特殊情况

有一些特殊情况:

	-bang	    这些命令可以使用一个 ! 修饰服 (和 :q 或 :w 类似)
	-bar	    这些命令可以跟随一个 "|" 和其它命令. 那么命令参数中就
		    不允许有 "|" . 用一个 " 可以开始一个注释.
	-register   给这些命令的第一个参数可以是一个可选的寄存器名
		    (和 :del, :put, :yank 类似).
	-buffer	    这些命令仅在当前缓冲里有效.

在 -count 和 -register 属性的情况里, 如果可选的参数被应用, 它会被从参数列
表中删除, 并且在分别的文本替换中有效.

文本替换

一个用户定义命令的文本替换被以特殊的变换序列来扫描, 使用 <...> 符号. 变换
序列被从命令行输入的值替换, 并且所有其它文本都被不变的拷贝. 结果字串被作为
一个 Ex 命令来执行. 如果初始的 < 变换序列前面有一个反斜杠, 该序列被不变的
拷贝.

有效的变换序列有

						*<line1>*
	<line1>	命令处理范围的开始行.
						*<line2>*
	<line2>	命令处理范围的末尾行.
						*<count>*
	<count>	被应用的任意数量 (在 '-range'
		和 '-count' 属性中描述过的).
						*<bang>*
	<bang>	(参考 '-bang' 属性) 扩展出一个 ! 如果该命令执行的
		时候带了一个 ! 修饰符, 否则什么也不扩展.
						*<reg>* *<register>*
	<reg>	(参考 '-register' 属性) 可选的寄存器, 如果指定的话.
		否则什么也不扩展. <register> 是它的一个同义词.
						*<args>*
	<args>	命令的参数, 与被提供的精确相同 (但正如上面提到过的, 任何
		数量值或寄存器会消耗一些参数, 这时它们已不是 <args> 的一
		部分了).
	<lt>	一个单独的 '<' (小于号) 字符.  在变换序列扩展时如果需要得到
		一个字面意义的大小于号的拷贝时需要. - 例如, 要获得 <bang>,
		使用 <lt>bang>.

							*<q-args>*
如果一个变换序列的最前两个字符是 "q-" (例如, <q-args>) 那么该值以一种使它在
用于一个表达式时有效的方式被引用. 这种方式把参数当做单个值.

要允许命令把它们的参数传送给一个用户定义的函数, 有一种特殊的形式 <f-args>
("function args"). 它在空格和Tab的地方分裂命令行参数, 分别的引用每个参数,
并且 <f-args> 序列被逗号分隔的引用参数列表所替换. 参考下面的 Mycmd 示例.
当没有参数时, <f-args> 也没有参数.

示例 >

   " 删除从这里到末尾的所有东西
   :com Ddel +,$d

   " 把当前缓冲改名
   :com -nargs=1 -bang -complete=file Ren f <args>|w<bang>

   " 用一个文件的内容来替换某个范围内的内容
   " (以一行输入所有这些东西)
   :com -range -nargs=1 -complete=file
	 Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d

   " 计算范围内的行数
   :com! -range -nargs=0 Lines :echo <line2> - <line1> + 1 "lines"

   " 调用一个用户函数 (<f-args> 的示例)
   :com -nargs=* Mycmd call Myfunc(<f-args>)

当被这样执行时: >
	:Mycmd arg1 arg2
它将调用: >
	:call Myfunc("arg1","arg2")

   :" 一个更实用的例子
   :function Allargs(command)
   :	let i = 0
   :	while i < argc()
   :	   if filereadable(argv(i))
   :	    execute "e " . argv(i)
   :	     execute a:command
   :      endif
   :      let i = i + 1
   :   endwhile
   :endfunction
   :command -nargs=+ -complete=command Allargs call Allargs(<q-args>)

命令 Allargs 以任意 Vim 命令作为参数并在参数列表里的所有文件上执行它. 使用示例
(注意使用 "e" 标志来忽略错误并且用 "update" 命令来写被修改的缓冲区):
	:Allargs %s/foo/bar/ge|update
它将调用: >
	:call Allargs("%s/foo/bar/ge|update")
<
当在一个脚本里定义一个用户命令时, 它可以调用局部与脚本中的函数并且使用映射
来局部于该脚本. 当用户调用用户命令时, 该命令将运行在定义它的脚本的上下文里,
如果一个命令中使用了 |<SID>| 的时候这很重要.

 vim:tw=78:ts=8:ft=help:norl: