[r209]: trunk / doc / if_lua.txt Maximize Restore History

Download this file

if_lua.txt    369 lines (307 with data), 12.9 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
*if_lua.txt* For Vim version 7.4. 最近更新: 2013年8月
VIM 参 考 手 册 by Luis Carvalho
译者: Willis
http://vimcdoc.sf.net
Vim 的 Lua 接口 *lua* *Lua*
1. 命令 |lua-commands|
2. vim 模块 |lua-vim|
3. 列表用户数据 |lua-list|
4. 字典用户数据 |lua-dict|
5. 函数引用用户数据 |lua-funcref|
6. 缓冲区用户数据 |lua-buffer|
7. 窗口用户数据 |lua-window|
8. luaeval 函数 |lua-luaeval|
{Vi 没有任何以上的命令}
仅当 Vim 编译时加入 |+lua| 特性时 Lua 接口才可用。
==============================================================================
1. 命令 *lua-commands*
*:lua*
:[range]lua {chunk}
执行 Lua 语言块 {chunk}。{Vi 无此功能}
示例:
>
:lua print("Hello, Vim!")
:lua local curbuf = vim.buffer() curbuf[7] = "line #7"
<
:[range]lua << {endmarker}
{script}
{endmarker}
执行 Lua 脚本 {script}。{Vi 无此功能}
注意: 如果编译时没有加入 Lua 特性,此命令不能工作。要
避免错误,见 |script-here|。
{endmarker} 之前_不能_有任何空白。如果 "<<" 之后的 {endmarker} 省略,{script}
之后必须加上句号 '.',就像 |:append| 和 |:insert| 命令那样。
这种形式的 |:lua| 命令主要用于在 Vim 脚本中嵌入 Lua 代码。
示例:
>
function! CurrentLineInfo()
lua << EOF
local linenr = vim.window().line
local curline = vim.buffer()[linenr]
print(string.format("Current line [%d] has %d chars",
linenr, #curline))
EOF
endfunction
<
*:luado*
:[range]luado {body} 在 [range] 行范围的每行执行 Lua 函数
"function (line,linenr) {body} end",其中,函数参数是
每行的文本,结尾的 <EOL> 不计,和当前的行号。函数返回
值为字符串时用来替代当前行的文本。缺省的 [range] 是整
个文件: "1,$"。
{Vi 无此功能}
示例:
>
:luado return string.format("%s\t%d", line:reverse(), #line)
:lua require"lpeg"
:lua -- balanced parenthesis grammar:
:lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" }
:luado if bp:match(line) then return "-->\t" .. line end
<
*:luafile*
:[range]luafile {file}
执行 Lua {file} 文件中的脚本。{Vi 无此功能}
整个参数用作单个文件名。
示例:
>
:luafile script.lua
:luafile %
<
以上的命令都可执行一段 Lua 代码块 (chunk),或从命令行 (:lua 和 :luado),或从文
件 (:luafile),并可给出行范围 [range]。和 Lua 解释器类似,每个代码块都有自己的
作用域,所以命令之间只有全局变量可以共享。所有的 Lua 缺省库都可用。此外,Lua
的 "print" 函数的输出重定向到 Vim 消息区,参数以空格而不是制表符分隔。
Lua 使用 "vim" 模块 (见 |lua-vim|) 来对 Vim 发出指令以及对缓冲区
(|lua-buffer|) 和窗口 (|lua-window|) 进行管理。不过在 |sandbox| 中执行命令时,
修改缓冲区内容、打开新缓冲区和改变光标位置的过程收到限制。
==============================================================================
2. vim 模块 *lua-vim*
Lua 通过 "vim" 模块和 Vim 进行接口。输入行范围的首末行分别存入 "vim.firstline"
和 "vim.lastline"。该模块也包含一些对缓冲区、窗口以及当前行查询的例程、Vim 调
用和命令执行,以及其它各种操作。
vim.list([arg]) 返回空列表或者,如果给出 "arg" 为带有数值键值
1, ..., n 的Lua 表 (即 "sequence"),返回列表
l,l[i] = arg[i] 对 i = 1, .., n (见 |List|)。
非数值的键值不用于列表的初始化。转换规则参见
|lua-eval|。示例: >
:lua t = {math.pi, false, say = 'hi'}
:echo luaeval('vim.list(t)')
:" [3.141593, 0], 'say' 被忽略
<
vim.dict([arg]) 返回空字典或者,如果给出 "arg" 为 Lua 表,返回
字典 d,d[k] = arg[k] 对所有 "arg" 中的字符串
键值 k (见 |Dictionary|)。数值键值转化为字符
串。非字符串的键值不用于列表的初始化。转换规则
参见 |lua-eval|。示例: >
:lua t = {math.pi, false, say = 'hi'}
:echo luaeval('vim.dict(t)')
:" {'say': 'hi'}, 数值键被忽略
<
vim.funcref({name}) 返回对应函数名 {name} 的函数引用 (参见
|Funcref|)。等价于 Vim 的 "function"。
vim.buffer([arg]) 如果 "arg" 是数值,返回缓冲区列表中编号为
"arg" 的缓冲区。如果 "arg" 为字符串,返回完整
明或简短名为 "arg" 的缓冲区。这两种情况下,如
果找不到缓冲区,返回 'nil'。此外,如果
"toboolean(arg)" 为 'true',返回缓冲区列表的首
个缓冲区,否则返回当前缓冲区。
vim.window([arg]) 如果 "arg" 是数值,返回编号为 "arg" 的窗口,如
果找不到,返回 'nil'。此外,如果
"toboolean(arg)" 为 'true',返回首个窗口,否则
返回当前窗口。
vim.type({arg}) 返回 {arg} 的类型。等价于 Lua 的 "type" 函数,
但若 {arg} 是列表、字典、缓冲区、窗口则分别返
回 "list"、"dict"、"funcref"、"buffer" 或
"window"。示例: >
:lua l = vim.list()
:lua print(type(l), vim.type(l))
:" userdata list
<
vim.command({cmd}) 执行 vim (ex 模式) 命令 {cmd}。
示例: >
:lua vim.command"set tw=60"
:lua vim.command"normal ddp"
<
vim.eval({expr}) 计算表达式 {expr} (见 |expression|),把结果转
化为 Lua 格式并返回。Vim 字符串和数值被直接转
为响应的 Lua 字符串和数值类型。Vim 列表和字典
被转化为 Lua 的用户数据 (userdata) (见
|lua-list| 和 |lua-dict|)。
示例: >
:lua tw = vim.eval"&tw"
:lua print(vim.eval"{'a': 'one'}".a)
<
vim.line() 返回当前行 (没有结尾的 <EOL>),Lua 字符串。
vim.beep() 鸣笛。
vim.open({fname}) 为文件 {fname} 打开新缓冲区并返回之。注意 并不
把该缓冲区设为当前缓冲区。
==============================================================================
3. 列表用户数据 *lua-list*
列表用户数据代表 vim 的列表,其接口尽量和 Vim 的列表语法相近。因为列表为对象,
Lua 中列表引用的改变会反映在 Vim 中,反之亦然。列表 "l" 有以下属性和方法:
属性
----------
o "#l" 是列表 "l" 的项目数,相当于 Vim 中的 "len(l)"。
o "l[k]" 返回 "l" 的第 k 项;"l" 索引从零开始,和 Vim 一样。要修改第 k
项,可用 "l[k] = newitem";特别地,"l[k] = nil" 删除 "l" 的第 k 项。
o "l()" 返回遍历 "l" 的 iterator。
方法
-------
o "l:add(item)" 在 "l" 尾部附加 "item" 项目。
o "l:insert(item[, pos])" 在可选的 "pos" 指定的位置上插入 "item" 项
目。"pos" 缺省值为 "0"。
示例:
>
:let l = [1, 'item']
:lua l = vim.eval('l') -- 相同的 'l'
:lua l:add(vim.list())
:lua l[0] = math.pi
:echo l[0] " 3.141593
:lua l[0] = nil -- 删除第一项
:lua l:insert(true, 1)
:lua print(l, #l, l[0], l[1], l[-1])
:lua for item in l() do print(item) end
<
==============================================================================
4. 字典用户数据 *lua-dict*
和列表用户数据类似,字典用户数据代表 vim 的字典;既然字典也是对象,Lua 和 Vim
共享对象的引用。字典 "d" 有以下属性:
属性
----------
o "#d" 是字典 "d" 的项目数,相当于 Vim 中的 "len(d)"。
o "d.key" 或 "d['key']" 返回 "d" "key" 对应项目的值。要修改其值,可用
"d.key = newvalue"; 特别地,"d[k] = nil" 删除 "d" 中的对应项目。
o "d()" 返回遍历 "d" 的 iterator,等价于 Vim 的 "items(d)"。
示例:
>
:let d = {'n':10}
:lua d = vim.eval('d') -- 相同的 'd'
:lua print(d, d.n, #d)
:let d.self = d
:lua for k, v in d() do print(d, k, v) end
:lua d.x = math.pi
:lua d.self = nil -- 删除项目
:echo d
<
==============================================================================
5. 函数引用用户数据 *lua-funcref*
函数引用用户数据代表 Vim 的函数引用变量。定义时带有 "dict" 属性的函数引用需通
过赋给某字典的一个键值来使其 "self" 对应该字典 (见下例)。函数引用 "f" 有以下属
性:
属性
----------
o "#f" 是 "f" 引用的函数名
o "f(...)" 调用 "f" 引用的函数 (带参数)
示例:
>
:function I(x)
: return a:x
: endfunction
:let R = function('I')
:lua i1 = vim.funcref('I')
:lua i2 = vim.eval('R')
:lua print(#i1, #i2) -- 都应返回 'I'
:lua print(i1, i2, #i2(i1) == #i1(i2))
:function Mylen() dict
: return len(self.data)
: endfunction
:let mydict = {'data': [0, 1, 2, 3]}
:lua d = vim.eval('mydict'); d.len = vim.funcref('Mylen')
:echo mydict.len()
:lua l = d.len -- 把 d 视为 'self'
:lua print(l())
<
+==============================================================================
6. 缓冲区用户数据 *lua-buffer*
缓冲区用户数据代表 vim 的缓冲区。缓冲区用户数据 "b" 包含以下属性和方法:
属性
----------
o "b()" 设置 "b" 为当前缓冲区。
o "#b" 是缓冲区 "b" 的行数。
o "b[k]" 代表行号 k: "b[k] = newline" 把第 "k" 行替换为字符串
"newline",还有 "b[k] = nil" 删除第 "k" 行。
o "b.name" 包含缓冲区 "b" 的简短名 (只读)。
o "b.fname" 包含缓冲区 "b" 的完整名 (只读)。
o "b.number" 包含缓冲区 "b" 在缓冲区列表的位置 (只读)。
方法
-------
o "b:insert(newline"[, pos]")" 在缓冲区 "pos" (可选) 位置插入
"newline" 字符串。"pos" 缺省值为 "#b + 1"。如果 "pos == 0",
"newline" 将成为缓冲区的首行。
o "b:next()" 返回缓冲区列表中 "b" 的下一个缓冲区。
o "b:previous()" 返回缓冲区列表 "b" 的前一个缓冲区。
o "b:isvalid()" 如果缓冲区 "b" 对应 "真正的" (内存没有释放的) Vim 缓
冲区时,返回 'true' (布尔值)。
示例:
>
:lua b = vim.buffer() -- 当前缓冲区
:lua print(b.name, b.number)
:lua b[1] = "first line"
:lua b:insert("FIRST!", 0)
:lua b[1] = nil -- 删除首行
:lua for i=1,3 do b:insert(math.random()) end
:3,4lua for i=vim.lastline,vim.firstline,-1 do b[i] = nil end
:lua vim.open"myfile"() -- 打开缓冲区,设为当前缓冲区
function! ListBuffers()
lua << EOF
local b = vim.buffer(true) -- 列表中的首个缓冲区
while b ~= nil do
print(b.number, b.name, #b)
b = b:next()
end
vim.beep()
EOF
endfunction
<
==============================================================================
7. 窗口用户数据 *lua-window*
窗口对象代表 vim 窗口。窗口用户数据 "w" 有以下属性和方法:
属性
----------
o "w()" 设置 "w" 为当前窗口。
o "w.buffer" 返回窗口 "w" 对应的缓冲区 (只读)。
o "w.line" 返回窗口 "w" 的光标行位置。
o "w.col" 返回窗口 "w" 的光标列位置。
o "w.width" 代表窗口 "w" 的宽度。
o "w.height" 代表窗口 "w" 的高度。
方法
-------
o "w:next()" 返回 "w" 的下一个窗口。
o "w:previous()" 返回 "w" 的前一个窗口。
o "w:isvalid()" 如果窗口 "w" 对应 "真正的" (内存没有释放的) Vim 窗
口,返回 'true' (布尔值)。
示例:
>
:lua w = vim.window() -- 当前窗口
:lua print(w.buffer.name, w.line, w.col)
:lua w.width = w.width + math.random(10)
:lua w.height = 2 * math.random() * w.height
:lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end
:lua print("有 " .. n .. " 个窗口")
<
==============================================================================
8. luaeval 函数 *lua-luaeval*
和 "vim.eval" 对应,"luaeval" 在 Vim 中接受 Lua 值的传入。"luaeval" 接受一个
表达式字符串以及一个可选的参数,并返回表达式计算的结果。语义上,等价于在 Lua
里进行如下的操作:
>
local chunkheader = "local _A = select(1, ...) return "
function luaeval (expstr, arg)
local chunk = assert(loadstring(chunkheader .. expstr, "luaeval"))
return chunk(arg) -- return typval
end
<
注意 "_A" 接收给 "luaeval" 的参数。Lua 数值,字符串,列表,字典和函数引用用户
数据转化为 Vim 对应的类型,Lua 布尔型转化为数值。试图转换其他 Lua 类型,包括
非列表、字典、函数引用的用户数据,会抛出错误。
示例: >
:echo luaeval('math.pi')
:lua a = vim.list():add('newlist')
:let a = luaeval('a')
:echo a[0] " 'newlist'
:function Rand(x,y) " random uniform between x and y
: return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y})
: endfunction
:echo Rand(1,10)
==============================================================================
vim:tw=78:ts=8:ft=help:norl: