403 lines
13 KiB
Text
403 lines
13 KiB
Text
*if_lua.txt* For Vim version 7.4. Last change: 2012 Jun 29
|
|
|
|
|
|
VIM REFERENCE MANUAL by Luis Carvalho
|
|
|
|
|
|
The Lua Interface to Vim *lua* *Lua*
|
|
|
|
1. Commands |lua-commands|
|
|
2. The vim module |lua-vim|
|
|
3. List userdata |lua-list|
|
|
4. Dict userdata |lua-dict|
|
|
5. Funcref userdata |lua-funcref|
|
|
6. Buffer userdata |lua-buffer|
|
|
7. Window userdata |lua-window|
|
|
8. The luaeval function |lua-luaeval|
|
|
|
|
{Vi does not have any of these commands}
|
|
|
|
The Lua interface is available only when Vim was compiled with the
|
|
|+lua| feature.
|
|
|
|
==============================================================================
|
|
1. Commands *lua-commands*
|
|
|
|
*:lua*
|
|
:[range]lua {chunk}
|
|
Execute Lua chunk {chunk}. {not in Vi}
|
|
|
|
Examples:
|
|
>
|
|
:lua print("Hello, Vim!")
|
|
:lua local curbuf = vim.buffer() curbuf[7] = "line #7"
|
|
<
|
|
|
|
:[range]lua << {endmarker}
|
|
{script}
|
|
{endmarker}
|
|
Execute Lua script {script}. {not in Vi}
|
|
Note: This command doesn't work when the Lua
|
|
feature wasn't compiled in. To avoid errors, see
|
|
|script-here|.
|
|
|
|
{endmarker} must NOT be preceded by any white space. If {endmarker} is
|
|
omitted from after the "<<", a dot '.' must be used after {script}, like
|
|
for the |:append| and |:insert| commands.
|
|
This form of the |:lua| command is mainly useful for including Lua code
|
|
in Vim scripts.
|
|
|
|
Example:
|
|
>
|
|
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} Execute Lua function "function (line, linenr) {body}
|
|
end" for each line in the [range], with the function
|
|
argument being set to the text of each line in turn,
|
|
without a trailing <EOL>, and the current line number.
|
|
If the value returned by the function is a string it
|
|
becomes the text of the line in the current turn. The
|
|
default for [range] is the whole file: "1,$".
|
|
{not in Vi}
|
|
|
|
Examples:
|
|
>
|
|
: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}
|
|
Execute Lua script in {file}. {not in Vi}
|
|
The whole argument is used as a single file name.
|
|
|
|
Examples:
|
|
>
|
|
:luafile script.lua
|
|
:luafile %
|
|
<
|
|
|
|
All these commands execute a Lua chunk from either the command line (:lua and
|
|
:luado) or a file (:luafile) with the given line [range]. Similarly to the Lua
|
|
interpreter, each chunk has its own scope and so only global variables are
|
|
shared between command calls. All Lua default libraries are available. In
|
|
addition, Lua "print" function has its output redirected to the Vim message
|
|
area, with arguments separated by a white space instead of a tab.
|
|
|
|
Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim
|
|
and manage buffers (|lua-buffer|) and windows (|lua-window|). However,
|
|
procedures that alter buffer content, open new buffers, and change cursor
|
|
position are restricted when the command is executed in the |sandbox|.
|
|
|
|
|
|
==============================================================================
|
|
2. The vim module *lua-vim*
|
|
|
|
Lua interfaces Vim through the "vim" module. The first and last line of the
|
|
input range are stored in "vim.firstline" and "vim.lastline" respectively. The
|
|
module also includes routines for buffer, window, and current line queries,
|
|
Vim evaluation and command execution, and others.
|
|
|
|
vim.list([arg]) Returns an empty list or, if "arg" is a Lua
|
|
table with numeric keys 1, ..., n (a
|
|
"sequence"), returns a list l such that l[i] =
|
|
arg[i] for i = 1, ..., n (see |List|).
|
|
Non-numeric keys are not used to initialize
|
|
the list. See also |lua-eval| for conversion
|
|
rules. Example: >
|
|
:lua t = {math.pi, false, say = 'hi'}
|
|
:echo luaeval('vim.list(t)')
|
|
:" [3.141593, 0], 'say' is ignored
|
|
<
|
|
vim.dict([arg]) Returns an empty dictionary or, if "arg" is a
|
|
Lua table, returns a dict d such that d[k] =
|
|
arg[k] for all string keys k in "arg" (see
|
|
|Dictionary|). Number keys are converted to
|
|
strings. Keys that are not strings are not
|
|
used to initialize the dictionary. See also
|
|
|lua-eval| for conversion rules. Example: >
|
|
:lua t = {math.pi, false, say = 'hi'}
|
|
:echo luaeval('vim.dict(t)')
|
|
:" {'say': 'hi'}, numeric keys ignored
|
|
<
|
|
vim.funcref({name}) Returns a Funcref to function {name} (see
|
|
|Funcref|). It is equivalent to Vim's
|
|
"function".
|
|
|
|
vim.buffer([arg]) If "arg" is a number, returns buffer with
|
|
number "arg" in the buffer list or, if "arg"
|
|
is a string, returns buffer whose full or short
|
|
name is "arg". In both cases, returns 'nil'
|
|
(nil value, not string) if the buffer is not
|
|
found. Otherwise, if "toboolean(arg)" is
|
|
'true' returns the first buffer in the buffer
|
|
list or else the current buffer.
|
|
|
|
vim.window([arg]) If "arg" is a number, returns window with
|
|
number "arg" or 'nil' (nil value, not string)
|
|
if not found. Otherwise, if "toboolean(arg)"
|
|
is 'true' returns the first window or else the
|
|
current window.
|
|
|
|
vim.type({arg}) Returns the type of {arg}. It is equivalent to
|
|
Lua's "type" function, but returns "list",
|
|
"dict", "funcref", "buffer", or "window" if
|
|
{arg} is a list, dictionary, funcref, buffer,
|
|
or window, respectively. Examples: >
|
|
:lua l = vim.list()
|
|
:lua print(type(l), vim.type(l))
|
|
:" userdata list
|
|
<
|
|
vim.command({cmd}) Executes the vim (ex-mode) command {cmd}.
|
|
Examples: >
|
|
:lua vim.command"set tw=60"
|
|
:lua vim.command"normal ddp"
|
|
<
|
|
vim.eval({expr}) Evaluates expression {expr} (see |expression|),
|
|
converts the result to Lua, and returns it.
|
|
Vim strings and numbers are directly converted
|
|
to Lua strings and numbers respectively. Vim
|
|
lists and dictionaries are converted to Lua
|
|
userdata (see |lua-list| and |lua-dict|).
|
|
Examples: >
|
|
:lua tw = vim.eval"&tw"
|
|
:lua print(vim.eval"{'a': 'one'}".a)
|
|
<
|
|
vim.line() Returns the current line (without the trailing
|
|
<EOL>), a Lua string.
|
|
|
|
vim.beep() Beeps.
|
|
|
|
vim.open({fname}) Opens a new buffer for file {fname} and
|
|
returns it. Note that the buffer is not set as
|
|
current.
|
|
|
|
|
|
==============================================================================
|
|
3. List userdata *lua-list*
|
|
|
|
List userdata represent vim lists, and the interface tries to follow closely
|
|
Vim's syntax for lists. Since lists are objects, changes in list references in
|
|
Lua are reflected in Vim and vice-versa. A list "l" has the following
|
|
properties and methods:
|
|
|
|
Properties
|
|
----------
|
|
o "#l" is the number of items in list "l", equivalent to "len(l)"
|
|
in Vim.
|
|
o "l[k]" returns the k-th item in "l"; "l" is zero-indexed, as in Vim.
|
|
To modify the k-th item, simply do "l[k] = newitem"; in
|
|
particular, "l[k] = nil" removes the k-th item from "l".
|
|
o "l()" returns an iterator for "l".
|
|
|
|
Methods
|
|
-------
|
|
o "l:add(item)" appends "item" to the end of "l".
|
|
o "l:insert(item[, pos])" inserts "item" at (optional)
|
|
position "pos" in the list. The default value for "pos" is 0.
|
|
|
|
Examples:
|
|
>
|
|
:let l = [1, 'item']
|
|
:lua l = vim.eval('l') -- same 'l'
|
|
:lua l:add(vim.list())
|
|
:lua l[0] = math.pi
|
|
:echo l[0] " 3.141593
|
|
:lua l[0] = nil -- remove first item
|
|
: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. Dict userdata *lua-dict*
|
|
|
|
Similarly to list userdata, dict userdata represent vim dictionaries; since
|
|
dictionaries are also objects, references are kept between Lua and Vim. A dict
|
|
"d" has the following properties:
|
|
|
|
Properties
|
|
----------
|
|
o "#d" is the number of items in dict "d", equivalent to "len(d)"
|
|
in Vim.
|
|
o "d.key" or "d['key']" returns the value at entry "key" in "d".
|
|
To modify the entry at this key, simply do "d.key = newvalue"; in
|
|
particular, "d.key = nil" removes the entry from "d".
|
|
o "d()" returns an iterator for "d" and is equivalent to "items(d)" in
|
|
Vim.
|
|
|
|
Examples:
|
|
>
|
|
:let d = {'n':10}
|
|
:lua d = vim.eval('d') -- same '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 -- remove entry
|
|
:echo d
|
|
<
|
|
|
|
==============================================================================
|
|
5. Funcref userdata *lua-funcref*
|
|
|
|
Funcref userdata represent funcref variables in Vim. Funcrefs that were
|
|
defined with a "dict" attribute need to be obtained as a dictionary key
|
|
in order to have "self" properly assigned to the dictionary (see examples
|
|
below.) A funcref "f" has the following properties:
|
|
|
|
Properties
|
|
----------
|
|
o "#f" is the name of the function referenced by "f"
|
|
o "f(...)" calls the function referenced by "f" (with arguments)
|
|
|
|
Examples:
|
|
>
|
|
: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) -- both '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 -- assign d as 'self'
|
|
:lua print(l())
|
|
<
|
|
|
|
==============================================================================
|
|
6. Buffer userdata *lua-buffer*
|
|
|
|
Buffer userdata represent vim buffers. A buffer userdata "b" has the following
|
|
properties and methods:
|
|
|
|
Properties
|
|
----------
|
|
o "b()" sets "b" as the current buffer.
|
|
o "#b" is the number of lines in buffer "b".
|
|
o "b[k]" represents line number k: "b[k] = newline" replaces line k
|
|
with string "newline" and "b[k] = nil" deletes line k.
|
|
o "b.name" contains the short name of buffer "b" (read-only).
|
|
o "b.fname" contains the full name of buffer "b" (read-only).
|
|
o "b.number" contains the position of buffer "b" in the buffer list
|
|
(read-only).
|
|
|
|
Methods
|
|
-------
|
|
o "b:insert(newline[, pos])" inserts string "newline" at (optional)
|
|
position "pos" in the buffer. The default value for "pos" is
|
|
"#b + 1". If "pos == 0" then "newline" becomes the first line in
|
|
the buffer.
|
|
o "b:next()" returns the buffer next to "b" in the buffer list.
|
|
o "b:previous()" returns the buffer previous to "b" in the buffer
|
|
list.
|
|
o "b:isvalid()" returns 'true' (boolean) if buffer "b" corresponds to
|
|
a "real" (not freed from memory) Vim buffer.
|
|
|
|
Examples:
|
|
>
|
|
:lua b = vim.buffer() -- current buffer
|
|
:lua print(b.name, b.number)
|
|
:lua b[1] = "first line"
|
|
:lua b:insert("FIRST!", 0)
|
|
:lua b[1] = nil -- delete top line
|
|
: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"() -- open buffer and set it as current
|
|
|
|
function! ListBuffers()
|
|
lua << EOF
|
|
local b = vim.buffer(true) -- first buffer in list
|
|
while b ~= nil do
|
|
print(b.number, b.name, #b)
|
|
b = b:next()
|
|
end
|
|
vim.beep()
|
|
EOF
|
|
endfunction
|
|
<
|
|
|
|
==============================================================================
|
|
7. Window userdata *lua-window*
|
|
|
|
Window objects represent vim windows. A window userdata "w" has the following
|
|
properties and methods:
|
|
|
|
Properties
|
|
----------
|
|
o "w()" sets "w" as the current window.
|
|
o "w.buffer" contains the buffer of window "w" (read-only).
|
|
o "w.line" represents the cursor line position in window "w".
|
|
o "w.col" represents the cursor column position in window "w".
|
|
o "w.width" represents the width of window "w".
|
|
o "w.height" represents the height of window "w".
|
|
|
|
Methods
|
|
-------
|
|
o "w:next()" returns the window next to "w".
|
|
o "w:previous()" returns the window previous to "w".
|
|
o "w:isvalid()" returns 'true' (boolean) if window "w" corresponds to
|
|
a "real" (not freed from memory) Vim window.
|
|
|
|
Examples:
|
|
>
|
|
:lua w = vim.window() -- current 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("There are " .. n .. " windows")
|
|
<
|
|
|
|
==============================================================================
|
|
8. The luaeval function *lua-luaeval* *lua-eval*
|
|
|
|
The (dual) equivalent of "vim.eval" for passing Lua values to Vim is
|
|
"luaeval". "luaeval" takes an expression string and an optional argument and
|
|
returns the result of the expression. It is semantically equivalent in Lua to:
|
|
>
|
|
local chunkheader = "local _A = select(1, ...) return "
|
|
function luaeval (expstr, arg)
|
|
local chunk = assert(loadstring(chunkheader .. expstr, "luaeval"))
|
|
return chunk(arg) -- return typval
|
|
end
|
|
<
|
|
Note that "_A" receives the argument to "luaeval". Lua numbers, strings, and
|
|
list, dict, and funcref userdata are converted to their Vim respective types,
|
|
while Lua booleans are converted to numbers. An error is thrown if conversion
|
|
of any of the remaining Lua types, including userdata other than lists, dicts,
|
|
and funcrefs, is attempted.
|
|
|
|
Examples: >
|
|
|
|
: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:noet:ft=help:norl:
|