2502vim,vim文本对象中文文档

介绍

文本块用户(textobj-user)是一个可帮助你毫不费力地创建自己的文本对象的Vim插件.

因为有许多陷阱需要处理,很难创建文本对象.此插件隐藏了此类细节,并提供了声明式定义文本对象的方法.

你可用正则式来定义简单的文本对象,或使用函数来定义复杂的文本对象.如…

`文本对象用户`简单示例

(a)定义"ad"/"id"以选择如"2013-03-16"的日期,及定义"at"/"it"以选择如"22:04:21"的时间:

call textobj#user#plugin("datetime", {
\   "date": {
\     "pattern": "\<\d\d\d\d-\d\d-\d\d\>",
\     "select": ["ad", "id"],
\   },
\   "time": {
\     "pattern": "\<\d\d:\d\d:\d\d\>",
\     "select": ["at", "it"],
\   },
\ })

`文本对象用户`示例之间

(b)定义"aA"以选择从"<<"到匹配的">>"的文本,及定义"iA"以选择"<<"和">>"中的文本:

call textobj#user#plugin("braces", {
\   "angle": {
\     "pattern": ["<<", ">>"],
\     "select-a": "aA",
\     "select-i": "iA",
\   },
\ })

`文本对象用户`示例之间

(c)定义"al"以选择当前行,并且定义"il"以选择不带缩进的当前行:

call textobj#user#plugin("line", {
\   "-": {
\     "select-a-function": "CurrentLineA",
\     "select-a": "al",
\     "select-i-function": "CurrentLineI",
\     "select-i": "il",
\   },
\ })

function! CurrentLineA()
  normal! 0
  let head_pos = getpos(".")
  normal! $
  let tail_pos = getpos(".")
  return ["v", head_pos, tail_pos]
endfunction
function! CurrentLineI()
  normal! ^
  let head_pos = getpos(".")
  normal! g_
  let tail_pos = getpos(".")
  let non_blank_char_exists_p = getline(".")[head_pos[2] - 1] !~# "\s"
  return
  \ non_blank_char_exists_p
  \ ? ["v", head_pos, tail_pos]
  \ : 0
endfunction

`文本对象用户`示例文件类型

(d)定义"a("来选择从"\left("到匹配的"\right)"中的文本,定义"i("选择从"\left("到匹配的"\right)"中的文本,但仅针对tex文件:

call textobj#user#plugin("tex", {
\   "parenmath": {
\     "pattern": ["\\left(", "\\right)"],
\     "select-a": [],
\     "select-i": [],
\   },
\ })
augroup tex_textobjs
  autocmd!
  autocmd FileType tex call textobj#user#map("tex", {
  \   "parenmath": {
  \     "select-a": "<buffer> a(",
  \     "select-i": "<buffer> i(",
  \   },
  \ })
augroup END

可如上例所示,定义自己的文本对象.

一点哲学

为什么要定义它们?你必须相信它们是有用的,它们可提高你的生产力.
此类文本对象对其他用户也很有用.但为何不按插件共享呢?
是,这就是textobjuser只提供一个textobj#user#plugin()函数的原因.它不仅为自定义文本对象(如aX/iX),定义了键映射,还按插件定义了要共享期望的一切.

如,对自定义文本对象,用户可能更喜欢aY/iY而不是aX/iX.因此,有必要为此自定义提供一个方法,但手动定义它们有点乏味.

`文本对象用户`参考

textobj#user#plugin()

textobj#user#plugin({插件名}, {规范})

根据{规范}自定义文本对象,而定义也轻松按名叫{插件名}的插件共享了自定义文本对象.{插件名}是一个由英文字母组成的串.
此名用作各种键映射,Ex命令和变量.

{规范}是自定义文本对象定义的字典.如:

call textobj#user#plugin("datetime", {
\   "date": {
\     "pattern": "\<\d\d\d\d-\d\d-\d\d\>",
\     "select": ["ad", "id"],
\   },
\   "time": {
\     "pattern": "\<\d\d:\d\d:\d\d\>",
\     "select": ["at", "it"],
\   },
\ })

许多东西都是用上面的定义定义的:

Textobj{Plugin}DefaultKeyMappings

(a)定义了一个Ex命令:TextobjDatetimeDefaultKeyMappings.
Ex命令对自定义文本对象定义了默认键映射.

但是它除非给出"!",它不会覆盖现有键映射.

在此例中,Ex命令给自定义文本对象,按符号待定模式和可视模式下映射"ad","id","at"和"it".
如果{左边}以(如<C-d>)不可打印的符开头,则也会在选择模式下映射{左边}.

(textobj-{plugin}-{object}-{operation})

(b)在符号待定(符号挂起)模式,可视(可视)模式和选择(选择)模式下,定义如<Plug>(textobj-datetime-date)接口键映射.

这些是为用户额外自定义而定义的.如,人们可能更喜欢"aT"和"iT"来选择时间,因为默认,at和it已用作非常有用的选择标签块的文本对象,一般覆盖它们不好.

此时,接口键映射的用法如下:

xmap aT  <Plug>(textobj-datetime-time)
omap aT  <Plug>(textobj-datetime-time)
xmap iT  <Plug>(textobj-datetime-time)
omap iT  <Plug>(textobj-datetime-time)

g:textobj_{plugin}_no_default_key_mappings

(c)最后,默认执行:TextobjDatetimeDefaultKeyMappings来定义默认键映射:"ad","id","at"和"it".如(b)中所述,有时用户不希望使用如"at"和"it"的默认键映射.

如果按真设置g:textobj_datetime_no_default_key_mappings,则不会定义默认键映射.为了后向兼容,如果{规范}包含键"*no-default-key-mappings*",则也不会定义默认键映射.

但此功能在未来的版本中会删除.

`textobjuser`规范

textobj#user#plugin()为自定义文本对象取{规范}.{规范}是一个字典,按一系列键是文本对象名,值是文本对象的规范的键值对对待它.

由各种属性组成文本对象的规范.按单个字典表示属性.每个键都是一个属性名.
以下属性可用:

"move-n" {左边} 或 [{左边}, ...]"

该值必须为串或串列表.按默认键映射的{左边}对待每个串,以移动光标到下个文本对象.
目标文本对象由带单个正则式的"模式"属性或"move-n函数"属性确定.

"move-p" {左边}或[{左边}, ...]
"move-N" {左边}或[{左边}, ...]
"move-P" {左边}或[{左边}, ...]

与"move-n"类似,但{左边}用作移动光标到上个文本对象,下个文本对象的结尾,或上个文本对象的结尾的默认键映射.

"select" {左边}或[{左边}, ...]"

与"move-n"类似,但{左边}用作选择光标下的文本对象的默认键映射.由有单个正则式的"模式"属性或"选择函数"属性确定目标文本对象.

"select-a" {左边}或[{左边}, ...]
"select-i" {左边}或[{左边}, ...]

与"选择"类似,但为了选择"a"文本对象或"内部"文本对象,按默认键映射使用{左边},如ab,ip和其他内置文本对象.

由带一对正则式的"模式"属性,"select-a-函数"属性或"select-i-函数"属性确定目标文本对象.

“模式” {regexp}或[{regexp},{regexp}]

确定目标文本对象的单个正则式或两个正则式的列表.
使用单个正则式:
按目标文本对象对待正则式匹配的区域.
使用一对正则式:
按目标文本对象对待两个部分间的区域,其中第1部分与第1个正则式匹配,第2部分与第2个正则式匹配.

`文本对象`用户区域类型

"regiontype" {符}(默认值:"v")
一个"模式"属性定义的用来指定区域类型的串.可能值如下:

值              意思
-------------------------------
"v"             按符
"V"             按行
"\<C-v>"        按块

`文本对象`用户扫描

"扫描" {串}(默认值:"前向")
一个用来指定如何为"选择"查找基于"模式"的文本对象的串.可能的值为:
"光标":试从光标下的文本中查找.
"前向":试从文本中查找:
(1)光标下
(2)光标后

"行":试从文本中查找:
(1)光标下方
(2)在当前行中和光标后
(3)在当前行中和光标前

"最近":试从文本中查找:
(1)光标下方
(2)在当前行中和光标后
(3)在当前行中和光标前
(4)当前行后
(5)当前行前

`"{property}-函数" {fname}`

如果定义了此属性,则使用名为{fname}的函数,而不是"模式"属性,来确定"{属性}"操作的目标文本对象.
函数,必须无参,且必须返回一个表示目标文本对象占据区域的列表,或必须返回0以表示没有文本对象.
表示区域的列表格式如下:
[region_type,start_position,end_position].

"region_type"是用来指定区域类型的单符串.
"start_position"表示区域的开始位置.
此值的细节与getpos()相同.
"end_position"类似"start_position",但它表示一个区域的结束位置.

“sfile” {串}

值必须是expand("<sfile>").此值用来计算针对"{属性}函数"的脚本本地函数的<SNR>前缀.

过时属性

仍可用,但会从未来的版本中删除.强烈建议改用新属性.

旧属性名	新属性名
`"模式"`	`"模式"`
`"{property}-function"`	`"{property}-函数"`
`"sfile"`	`"sfile"`
`"no-default-key-mappings"`	`不可用`

注意,"*no-default-key-mappings*"仍可用,但不再支持.
请改用g:textobj_{plugin}_no_default_key_mappings.

textobj#user#map()

textobj#user#map({插件名}, {规范})

定义键映射以使用自定义文本对象.大多数文本对象插件都提供默认键映射以使用自定义文本对象.但有时想改用其他键映射.
可在没有textobj#user#map()时如下定义此键映射,如:

xmap aT  <Plug>(textobj-datetime-time)
omap aT  <Plug>(textobj-datetime-time)
xmap iT  <Plug>(textobj-datetime-time)
omap iT  <Plug>(textobj-datetime-time)

但这很无聊.你可用textobj#user#map()按声明性的方式定义这些键映射.如:

call textobj#user#map("datetime", {
\   "time": {
\     "select": ["aT", "iT"],
\   }
\ })

{插件名}是文本对象插件名.

{规范}是一个包含自定义文本对象的定义的字典.与textobj#user#plugin()不同,只允许使用以下属性:

move-n      move-p      move-N      move-P
select      select-a    select-i

为了方便自定义,在调用textobj#user#map()时,可能未定义,{插件名}指定的文本对象插件.因为:
1,主要在vimrc中用textobj#user#map().文本对象插件一般在plugin/*.vim中.而vimrc在所有plugin/*.vim前加载.

2,有时在文件类型插件中使用textobj#user#map().特定文件类型的文本对象插件在ftplugin/*.vim中.一般,不可预测这些文件类型插件的加载顺序.

因此,textobj#user#map()无法检测{插件名}是否正确.这样实际是,当使用了textobj#user#map()定义的键映射,且此时没有相应的文本对象,则报错.

textobj#user#move()

textobj#user#move({模式}, {flags}, {上个模式})

移动光标到{模式}定义的相应对象.
{标志}是一个可包含以下符标志的串:

`符`	含义
`"b"`	`后向搜索`而不是`向前搜索`.
`"e"`	`移动`到`匹配尾`.

{上个模式},是一个表示"上个"模式的串,即哪种映射模式导致调用此函数.如,如果此函数是通过符号待定模式的映射调用的,则{上个模式}必须为"o".

`符`	含义
`"n"`	`普通`模式
`"o"`	`符号待定`模式
`"v"`	`可视`模式

返回值与searchpos()相同.

textobj#user#select()

textobj#user#select({模式}, {flags}, {prevous-mode})

选择由{模式}定义的适当对象.扫描以下位置以查找合适的对象:
(1)光标下方
(2)在当前行里和光标后
(3)在当前行里和光标前
(4)当前行后
(5)当前行前

{标志}是一个可包含以下符标志的串:

符	含义
`"b"`	从`(1),(3),(5)`中`查找对象`.
`"c"`	从`(1)`中`查找对象`.
`"f"`	从`(1),(2),(4)`中`查找对象`.(默认)
`"l"`	从`(1),(2),(3)`中`查找对象`.
`"n"`	从`(1),(2),(3),(4),(5)`中`查找对象`.
`"v"`	`按符选择对象`.(默认)
`"V"`	`选择对象`.
`"\<C-v>"`	`按块选择一个对象`.
`"N"`	查找`范围`但不`选择`.

{上个模式}的细节,见textobj#user#move().此函数返回对象的开始位置和结束位置列表.每个位置都是[{lnum},{col}].如果没有合适的对象,则返回0.

textobj#user#select_pair()

textobj#user#select_pair({1模式}, {2模式}, {flags}, {上个模式})

选择以{1模式}开头,并以{2模式}结尾的相应对象.{标志}是一个可包含以下符标志的串:

符	含义
`"a"`	选择包括`{1模式}`和`{2模式}`的范围,如`at`.
`"i"`	选择不包括`{1模式}`和`{2模式}`的范围,与`it`一样.除非`显式`指定`"a"`,否则这是`默认`.如果`光标`不在`{1模式}`和`{2模式}`间的文本中,则此函数闲着.
`"v"`	`按符选择对象`.(默认)
`"V"`	`选择对象`.
`"\<C-v>"`	`按块选择一个对象`.

有关{上个模式}的细节,见textobj#user#move().
未定义返回值.

问题

因为计数的含义根据每个自定义文本对象而变,vim-textobj-user不支持计数.如果要支持自定义文本对象的计数,请使用"{属性}-函数"定义它,并使用v:count和/或v:count1取实际计数.

对内置文本对象(如aw,ip等),通过重复文本对象(如"vawawaw...")来扩展视觉选择的区域.vimtextobjuser不支持该扩展.
因为支持所有自定义文本对象很难.虽然某些文本对象(如aw)只是扩展当前选择,但其他文本对象(如ab)可能会根据环境覆盖当前选择.