551 lines
18 KiB
Plaintext
551 lines
18 KiB
Plaintext
*if_lua.txt* For Vim version 9.1. Last change: 2021 Aug 06
|
|
|
|
|
|
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. Blob userdata |lua-blob|
|
|
6. Funcref userdata |lua-funcref|
|
|
7. Buffer userdata |lua-buffer|
|
|
8. Window userdata |lua-window|
|
|
9. luaeval() Vim function |lua-luaeval|
|
|
10. Dynamic loading |lua-dynamic|
|
|
|
|
{only available when Vim was compiled with the |+lua| feature}
|
|
|
|
==============================================================================
|
|
1. Commands *lua-commands*
|
|
|
|
*:lua*
|
|
:[range]lua {chunk}
|
|
Execute Lua chunk {chunk}.
|
|
|
|
Examples:
|
|
>
|
|
:lua print("Hello, Vim!")
|
|
:lua local curbuf = vim.buffer() curbuf[7] = "line #7"
|
|
<
|
|
|
|
:[range]lua << [trim] [{endmarker}]
|
|
{script}
|
|
{endmarker}
|
|
Execute Lua script {script}.
|
|
Note: This command doesn't work when the Lua
|
|
feature wasn't compiled in. To avoid errors, see
|
|
|script-here|.
|
|
|
|
If [endmarker] is omitted from after the "<<", a dot '.' must be used after
|
|
{script}, like for the |:append| and |:insert| commands. Refer to
|
|
|:let-heredoc| for more information.
|
|
|
|
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
|
|
<
|
|
To see what version of Lua you have: >
|
|
:lua print(_VERSION)
|
|
|
|
If you use LuaJIT you can also use this: >
|
|
:lua print(jit.version)
|
|
<
|
|
|
|
*: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,$".
|
|
|
|
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}.
|
|
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, v:false], '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)')
|
|
:" {'1': 3.141593, '2': v:false,
|
|
:" 'say': 'hi'}
|
|
<
|
|
vim.blob([arg]) Returns an empty blob or, if "arg" is a Lua
|
|
string, returns a blob b such that b is
|
|
equivalent to "arg" as a byte string.
|
|
Examples: >
|
|
:lua s = "12ab\x00\x80\xfe\xff"
|
|
:echo luaeval('vim.blob(s)')
|
|
:" 0z31326162.0080FEFF
|
|
<
|
|
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))
|
|
:" list
|
|
<
|
|
vim.command({cmds}) Executes one or more lines of Ex-mode commands
|
|
in {cmds}.
|
|
Examples: >
|
|
:lua vim.command"set tw=60"
|
|
:lua vim.command"normal ddp"
|
|
lua << trim END
|
|
vim.command([[
|
|
new Myfile.js
|
|
call search('start')
|
|
]])
|
|
END
|
|
<
|
|
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.
|
|
|
|
vim.call({name} [, {args}])
|
|
Proxy to call Vim function named {name} with
|
|
arguments {args}. Example: >
|
|
:lua print(vim.call('has', 'timers'))
|
|
<
|
|
vim.fn Proxy to call Vim functions. Proxy methods are
|
|
created on demand. Example: >
|
|
:lua print(vim.fn.has('timers'))
|
|
<
|
|
vim.lua_version The Lua version Vim was compiled with, in the
|
|
form {major}.{minor}.{patch}, e.g. "5.1.4".
|
|
|
|
vim.version() Returns a Lua table with the Vim version.
|
|
The table will have the following keys:
|
|
major - major Vim version.
|
|
minor - minor Vim version.
|
|
patch - latest patch included.
|
|
|
|
*lua-vim-variables*
|
|
The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
|
|
from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
|
|
described below. In this way you can easily read and modify global Vim script
|
|
variables from Lua.
|
|
|
|
Example: >
|
|
|
|
vim.g.foo = 5 -- Set the g:foo Vim script variable.
|
|
print(vim.g.foo) -- Get and print the g:foo Vim script variable.
|
|
vim.g.foo = nil -- Delete (:unlet) the Vim script variable.
|
|
|
|
vim.g *vim.g*
|
|
Global (|g:|) editor variables.
|
|
Key with no value returns `nil`.
|
|
|
|
vim.b *vim.b*
|
|
Buffer-scoped (|b:|) variables for the current buffer.
|
|
Invalid or unset key returns `nil`.
|
|
|
|
vim.w *vim.w*
|
|
Window-scoped (|w:|) variables for the current window.
|
|
Invalid or unset key returns `nil`.
|
|
|
|
vim.t *vim.t*
|
|
Tabpage-scoped (|t:|) variables for the current tabpage.
|
|
Invalid or unset key returns `nil`.
|
|
|
|
vim.v *vim.v*
|
|
|v:| variables.
|
|
Invalid or unset key returns `nil`.
|
|
|
|
==============================================================================
|
|
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:
|
|
|
|
NOTE: In patch 8.2.1066 array indexes were changed from zero-based to
|
|
one-based. You can check with: >
|
|
if has("patch-8.2.1066")
|
|
|
|
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 one-indexed, as in Lua.
|
|
To modify the k-th item, simply do "l[k] = newitem"; in
|
|
particular, "l[k] = nil" removes the k-th item from "l". Item can
|
|
be added to the end of the list by "l[#l + 1] = newitem"
|
|
o "l()" returns an iterator for "l".
|
|
o "table.insert(l, newitem)" inserts an item at the end of the list.
|
|
(only Lua 5.3 and later)
|
|
o "table.insert(l, position, newitem)" inserts an item at the
|
|
specified position. "position" is one-indexed. (only Lua 5.3 and
|
|
later)
|
|
o "table.remove(l, position)" removes an item at the specified
|
|
position. "position" is one-indexed.
|
|
|
|
|
|
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[1] = math.pi
|
|
:echo l[0] " 3.141593
|
|
:lua l[1] = nil -- remove first item
|
|
:lua l:insert(true, 1)
|
|
:lua print(l, #l, l[1], l[2])
|
|
:lua l[#l + 1] = 'value'
|
|
:lua table.insert(l, 100)
|
|
:lua table.insert(l, 2, 200)
|
|
:lua table.remove(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. Blob userdata *lua-blob*
|
|
|
|
Blob userdata represent vim blobs. A blob "b" has the following properties:
|
|
|
|
Properties
|
|
----------
|
|
o "#b" is the length of blob "b", equivalent to "len(b)" in Vim.
|
|
o "b[k]" returns the k-th item in "b"; "b" is zero-indexed, as in Vim.
|
|
To modify the k-th item, simply do "b[k] = number"; in particular,
|
|
"b[#b] = number" can append a byte to tail.
|
|
|
|
Methods
|
|
-------
|
|
o "b:add(bytes)" appends "bytes" to the end of "b".
|
|
|
|
Examples:
|
|
>
|
|
:let b = 0z001122
|
|
:lua b = vim.eval('b') -- same 'b'
|
|
:lua print(b, b[0], #b)
|
|
:lua b[1] = 32
|
|
:lua b[#b] = 0x33 -- append a byte to tail
|
|
:lua b:add("\x80\x81\xfe\xff")
|
|
:echo b
|
|
<
|
|
|
|
==============================================================================
|
|
6. 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())
|
|
<
|
|
Lua functions and closures are automatically converted to a Vim |Funcref| and
|
|
can be accessed in Vim scripts. Example:
|
|
>
|
|
lua <<EOF
|
|
vim.fn.timer_start(1000, function(timer)
|
|
print('timer callback')
|
|
end)
|
|
EOF
|
|
|
|
==============================================================================
|
|
7. 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
|
|
<
|
|
|
|
==============================================================================
|
|
8. 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")
|
|
<
|
|
|
|
==============================================================================
|
|
9. luaeval() Vim 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, blob, 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, blobs, 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)
|
|
|
|
|
|
==============================================================================
|
|
10. Dynamic loading *lua-dynamic*
|
|
|
|
On MS-Windows and Unix the Lua library can be loaded dynamically. The
|
|
|:version| output then includes |+lua/dyn|.
|
|
|
|
This means that Vim will search for the Lua DLL or shared library file only
|
|
when needed. When you don't use the Lua interface you don't need it, thus
|
|
you can use Vim without this file.
|
|
|
|
|
|
MS-Windows ~
|
|
|
|
To use the Lua interface the Lua DLL must be in your search path. In a
|
|
console window type "path" to see what directories are used. The 'luadll'
|
|
option can be also used to specify the Lua DLL. The version of the DLL must
|
|
match the Lua version Vim was compiled with.
|
|
|
|
|
|
Unix ~
|
|
|
|
The 'luadll' option can be used to specify the Lua shared library file instead
|
|
of DYNAMIC_LUA_DLL file what was specified at compile time. The version of
|
|
the shared library must match the Lua version Vim was compiled with.
|
|
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|