codekingpro/portable-devtools

1*if_lua.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Luis Carvalho5 6 7The Lua Interface to Vim				*lua* *Lua*8 91. Commands			|lua-commands|102. The vim module		|lua-vim|113. List userdata		|lua-list|124. Dict userdata		|lua-dict|135. Blob userdata		|lua-blob|146. Funcref userdata		|lua-funcref|157. Buffer userdata		|lua-buffer|168. Window userdata		|lua-window|179. luaeval() Vim function	|lua-luaeval|1810. Dynamic loading		|lua-dynamic|19 20{only available when Vim was compiled with the |+lua| feature}21 22==============================================================================231. Commands						*lua-commands*24 25							*:lua*26:[range]lua {chunk}27			Execute Lua chunk {chunk}.28 29Examples:30>31	:lua print("Hello, Vim!")32	:lua local curbuf = vim.buffer() curbuf[7] = "line #7"33<34 35:[range]lua << [trim] [{endmarker}]36{script}37{endmarker}38			Execute Lua script {script}.39			Note: This command doesn't work when the Lua40			feature wasn't compiled in.  To avoid errors, see41			|script-here|.42 43If [endmarker] is omitted from after the "<<", a dot '.' must be used after44{script}, like for the |:append| and |:insert| commands.  Refer to45|:let-heredoc| for more information.46 47This form of the |:lua| command is mainly useful for including Lua code48in Vim scripts.49 50Example:51>52	function! CurrentLineInfo()53	lua << EOF54	local linenr = vim.window().line55	local curline = vim.buffer()[linenr]56	print(string.format("Current line [%d] has %d chars",57		linenr, #curline))58	EOF59	endfunction60<61To see what version of Lua you have: >62	:lua print(_VERSION)63 64If you use LuaJIT you can also use this: >65	:lua print(jit.version)66<67 68							*:luado*69:[range]luado {body}	Execute Lua function "function (line, linenr) {body}70			end" for each line in the [range], with the function71			argument being set to the text of each line in turn,72			without a trailing <EOL>, and the current line number.73			If the value returned by the function is a string it74			becomes the text of the line in the current turn.  The75			default for [range] is the whole file: "1,$".76 77Examples:78>79	:luado return string.format("%s\t%d", line:reverse(), #line)80 81	:lua require"lpeg"82	:lua -- balanced parenthesis grammar:83	:lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" }84	:luado if bp:match(line) then return "-->\t" .. line end85<86 87							*:luafile*88:[range]luafile {file}89			Execute Lua script in {file}.90			The whole argument is used as a single file name.91 92Examples:93>94	:luafile script.lua95	:luafile %96<97 98All these commands execute a Lua chunk from either the command line (:lua and99:luado) or a file (:luafile) with the given line [range].  Similarly to the100Lua interpreter, each chunk has its own scope and so only global variables are101shared between command calls.  All Lua default libraries are available.  In102addition, Lua "print" function has its output redirected to the Vim message103area, with arguments separated by a white space instead of a tab.104 105Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim106and manage buffers (|lua-buffer|) and windows (|lua-window|).  However,107procedures that alter buffer content, open new buffers, and change cursor108position are restricted when the command is executed in the |sandbox|.109 110 111==============================================================================1122. The vim module					*lua-vim*113 114Lua interfaces Vim through the "vim" module.  The first and last line of the115input range are stored in "vim.firstline" and "vim.lastline" respectively.116The module also includes routines for buffer, window, and current line117queries, Vim evaluation and command execution, and others.118 119	vim.list([arg])		Returns an empty list or, if "arg" is a Lua120				table with numeric keys 1, ..., n (a121				"sequence"), returns a list l such that l[i] =122				arg[i] for i = 1, ..., n (see |List|).123				Non-numeric keys are not used to initialize124				the list.  See also |lua-eval| for conversion125				rules.  Example: >126				    :lua t = {math.pi, false, say = 'hi'}127				    :echo luaeval('vim.list(t)')128				    :" [3.141593, v:false], 'say' is ignored129<130	vim.dict([arg])		Returns an empty dictionary or, if "arg" is a131				Lua table, returns a dict d such that d[k] =132				arg[k] for all string keys k in "arg" (see133				|Dictionary|).  Number keys are converted to134				strings.  Keys that are not strings are not135				used to initialize the dictionary.  See also136				|lua-eval| for conversion rules.  Example: >137				    :lua t = {math.pi, false, say = 'hi'}138				    :echo luaeval('vim.dict(t)')139				    :" {'1': 3.141593, '2': v:false,140				    :" 'say': 'hi'}141<142	vim.blob([arg])		Returns an empty blob or, if "arg" is a Lua143				string, returns a blob b such that b is144				equivalent to "arg" as a byte string.145				Examples: >146				    :lua s = "12ab\x00\x80\xfe\xff"147				    :echo luaeval('vim.blob(s)')148				    :" 0z31326162.0080FEFF149<150	vim.funcref({name})	Returns a Funcref to function {name} (see151				|Funcref|).  It is equivalent to Vim's152				function().153 154	vim.buffer([arg])	If "arg" is a number, returns buffer with155				number "arg" in the buffer list or, if "arg"156				is a string, returns buffer whose full or157				short name is "arg".  In both cases, returns158				'nil' (nil value, not string) if the buffer is159				not found.  Otherwise, if "toboolean(arg)" is160				'true' returns the first buffer in the buffer161				list or else the current buffer.162 163	vim.window([arg])	If "arg" is a number, returns window with164				number "arg" or 'nil' (nil value, not string)165				if not found.  Otherwise, if "toboolean(arg)"166				is 'true' returns the first window or else the167				current window.168 169	vim.type({arg})		Returns the type of {arg}.  It is equivalent170				to Lua's "type" function, but returns "list",171				"dict", "funcref", "buffer", or "window" if172				{arg} is a list, dictionary, funcref, buffer,173				or window, respectively.  Examples: >174					:lua l = vim.list()175					:lua print(type(l), vim.type(l))176					:" list177<178	vim.command({cmds})	Executes one or more lines of Ex-mode commands179				in {cmds}.180				Examples: >181					:lua vim.command"set tw=60"182					:lua vim.command"normal ddp"183					lua << trim END184					  vim.command([[185					      new Myfile.js186					      call search('start')187					  ]])188					END189<190	vim.eval({expr})	Evaluates expression {expr} (see |expression|),191				converts the result to Lua, and returns it.192				Vim strings and numbers are directly converted193				to Lua strings and numbers respectively.  Vim194				lists and dictionaries are converted to Lua195				userdata (see |lua-list| and |lua-dict|).196				Examples: >197					:lua tw = vim.eval"&tw"198					:lua print(vim.eval"{'a': 'one'}".a)199<200	vim.line()		Returns the current line (without the trailing201				<EOL>), a Lua string.202 203	vim.beep()		Beeps.204 205	vim.open({fname})	Opens a new buffer for file {fname} and206				returns it.  Note that the buffer is not set207				as current.208 209	vim.call({name} [, {args}])210				Proxy to call Vim function named {name} with211				arguments {args}.  Example: >212					:lua print(vim.call('has', 'timers'))213<214	vim.fn			Proxy to call Vim functions.  Proxy methods215				are created on demand.  Example: >216					:lua print(vim.fn.has('timers'))217<218	vim.lua_version		The Lua version Vim was compiled with, in the219				form {major}.{minor}.{patch}, e.g. "5.1.4".220 221	vim.version()		Returns a Lua table with the Vim version.222				The table will have the following keys:223					major - major Vim version.224					minor - minor Vim version.225					patch - latest patch included.226 227                                                        *lua-vim-variables*228The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed229from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables230described below.  In this way you can easily read and modify global Vim script231variables from Lua.232 233Example: >234 235    vim.g.foo = 5     -- Set the g:foo Vim script variable.236    print(vim.g.foo)  -- Get and print the g:foo Vim script variable.237    vim.g.foo = nil   -- Delete (:unlet) the Vim script variable.238 239vim.g                                                   *vim.g*240        Global (|g:|) editor variables.241        Key with no value returns `nil`.242 243vim.b                                                   *vim.b*244        Buffer-scoped (|b:|) variables for the current buffer.245        Invalid or unset key returns `nil`.246 247vim.w                                                   *vim.w*248        Window-scoped (|w:|) variables for the current window.249        Invalid or unset key returns `nil`.250 251vim.t                                                   *vim.t*252        Tabpage-scoped (|t:|) variables for the current tabpage.253        Invalid or unset key returns `nil`.254 255vim.v                                                   *vim.v*256        |v:| variables.257        Invalid or unset key returns `nil`.258 259==============================================================================2603. List userdata					*lua-list*261 262List userdata represent vim lists, and the interface tries to follow closely263Vim's syntax for lists.  Since lists are objects, changes in list references264in Lua are reflected in Vim and vice-versa.  A list "l" has the following265properties and methods:266 267NOTE: In patch 8.2.1066 array indexes were changed from zero-based to268one-based.  You can check with: >269	    if has("patch-8.2.1066")270 271Properties272----------273	o "#l" is the number of items in list "l", equivalent to "len(l)"274	    in Vim.275	o "l[k]" returns the k-th item in "l"; "l" is one-indexed, as in Lua.276	    To modify the k-th item, simply do "l[k] = newitem"; in277	    particular, "l[k] = nil" removes the k-th item from "l".  Item can278	    be added to the end of the list by "l[#l + 1] = newitem"279	o "l()" returns an iterator for "l".280	o "table.insert(l, newitem)" inserts an item at the end of the list.281	    (only Lua 5.3 and later)282	o "table.insert(l, position, newitem)" inserts an item at the283	    specified position.  "position" is one-indexed.  (only Lua 5.3 and284	    later)285	o "table.remove(l, position)" removes an item at the specified286	    position.  "position" is one-indexed.287 288 289Methods290-------291	o "l:add(item)" appends "item" to the end of "l".292	o "l:insert(item[, pos])" inserts "item" at (optional)293	    position "pos" in the list.  The default value for "pos" is 0.294 295Examples:296>297	:let l = [1, 'item']298	:lua l = vim.eval('l') -- same 'l'299	:lua l:add(vim.list())300	:lua l[1] = math.pi301	:echo l[0] " 3.141593302	:lua l[1] = nil -- remove first item303	:lua l:insert(true, 1)304	:lua print(l, #l, l[1], l[2])305	:lua l[#l + 1] = 'value'306	:lua table.insert(l, 100)307	:lua table.insert(l, 2, 200)308	:lua table.remove(l, 1)309	:lua for item in l() do print(item) end310 311==============================================================================3124. Dict userdata					*lua-dict*313 314Similarly to list userdata, dict userdata represent vim dictionaries; since315dictionaries are also objects, references are kept between Lua and Vim.  A316dict "d" has the following properties:317 318Properties319----------320	o "#d" is the number of items in dict "d", equivalent to "len(d)"321	    in Vim.322	o "d.key" or "d['key']" returns the value at entry "key" in "d".323	    To modify the entry at this key, simply do "d.key = newvalue"; in324	    particular, "d.key = nil" removes the entry from "d".325	o "d()" returns an iterator for "d" and is equivalent to "items(d)" in326	    Vim.327 328Examples:329>330	:let d = {'n':10}331	:lua d = vim.eval('d') -- same 'd'332	:lua print(d, d.n, #d)333	:let d.self = d334	:lua for k, v in d() do print(d, k, v) end335	:lua d.x = math.pi336	:lua d.self = nil -- remove entry337	:echo d338<339 340==============================================================================3415. Blob userdata					*lua-blob*342 343Blob userdata represent vim blobs.  A blob "b" has the following properties:344 345Properties346----------347	o "#b" is the length of blob "b", equivalent to "len(b)" in Vim.348	o "b[k]" returns the k-th item in "b"; "b" is zero-indexed, as in Vim.349	    To modify the k-th item, simply do "b[k] = number"; in particular,350	    "b[#b] = number" can append a byte to tail.351 352Methods353-------354	o "b:add(bytes)" appends "bytes" to the end of "b".355 356Examples:357>358	:let b = 0z001122359	:lua b = vim.eval('b') -- same 'b'360	:lua print(b, b[0], #b)361	:lua b[1] = 32362	:lua b[#b] = 0x33 -- append a byte to tail363	:lua b:add("\x80\x81\xfe\xff")364	:echo b365<366 367==============================================================================3686. Funcref userdata					*lua-funcref*369 370Funcref userdata represent funcref variables in Vim.  Funcrefs that were371defined with a "dict" attribute need to be obtained as a dictionary key372in order to have "self" properly assigned to the dictionary (see examples373below.) A funcref "f" has the following properties:374 375Properties376----------377	o "#f" is the name of the function referenced by "f"378	o "f(...)" calls the function referenced by "f" (with arguments)379 380Examples:381>382	:function I(x)383	:  return a:x384	:  endfunction385	:let R = function('I')386	:lua i1 = vim.funcref('I')387	:lua i2 = vim.eval('R')388	:lua print(#i1, #i2) -- both 'I'389	:lua print(i1, i2, #i2(i1) == #i1(i2))390	:function Mylen() dict391	:  return len(self.data)392	:  endfunction393	:let mydict = {'data': [0, 1, 2, 3]}394	:lua d = vim.eval('mydict'); d.len = vim.funcref('Mylen')395	:echo mydict.len()396	:lua l = d.len -- assign d as 'self'397	:lua print(l())398<399Lua functions and closures are automatically converted to a Vim |Funcref| and400can be accessed in Vim scripts.  Example:401>402	lua <<EOF403	vim.fn.timer_start(1000, function(timer)404	    print('timer callback')405	end)406	EOF407 408==============================================================================4097. Buffer userdata					*lua-buffer*410 411Buffer userdata represent vim buffers.  A buffer userdata "b" has the412following properties and methods:413 414Properties415----------416	o "b()" sets "b" as the current buffer.417	o "#b" is the number of lines in buffer "b".418	o "b[k]" represents line number k: "b[k] = newline" replaces line k419	    with string "newline" and "b[k] = nil" deletes line k.420	o "b.name" contains the short name of buffer "b" (read-only).421	o "b.fname" contains the full name of buffer "b" (read-only).422	o "b.number" contains the position of buffer "b" in the buffer list423	    (read-only).424 425Methods426-------427	o "b:insert(newline[, pos])" inserts string "newline" at (optional)428	    position "pos" in the buffer.  The default value for "pos" is429	    "#b + 1".  If "pos == 0" then "newline" becomes the first line in430	    the buffer.431	o "b:next()" returns the buffer next to "b" in the buffer list.432	o "b:previous()" returns the buffer previous to "b" in the buffer433	    list.434	o "b:isvalid()" returns 'true' (boolean) if buffer "b" corresponds to435	    a "real" (not freed from memory) Vim buffer.436 437Examples:438>439	:lua b = vim.buffer() -- current buffer440	:lua print(b.name, b.number)441	:lua b[1] = "first line"442	:lua b:insert("FIRST!", 0)443	:lua b[1] = nil -- delete top line444	:lua for i=1,3 do b:insert(math.random()) end445	:3,4lua for i=vim.lastline,vim.firstline,-1 do b[i] = nil end446	:lua vim.open"myfile"() -- open buffer and set it as current447 448	function! ListBuffers()449	lua << EOF450	local b = vim.buffer(true) -- first buffer in list451	while b ~= nil do452		print(b.number, b.name, #b)453		b = b:next()454	end455	vim.beep()456	EOF457	endfunction458<459 460==============================================================================4618. Window userdata					*lua-window*462 463Window objects represent vim windows.  A window userdata "w" has the following464properties and methods:465 466Properties467----------468	o "w()" sets "w" as the current window.469	o "w.buffer" contains the buffer of window "w" (read-only).470	o "w.line" represents the cursor line position in window "w".471	o "w.col" represents the cursor column position in window "w".472	o "w.width" represents the width of window "w".473	o "w.height" represents the height of window "w".474 475Methods476-------477	o "w:next()" returns the window next to "w".478	o "w:previous()" returns the window previous to "w".479	o "w:isvalid()" returns 'true' (boolean) if window "w" corresponds to480	    a "real" (not freed from memory) Vim window.481 482Examples:483>484	:lua w = vim.window() -- current window485	:lua print(w.buffer.name, w.line, w.col)486	:lua w.width = w.width + math.random(10)487	:lua w.height = 2 * math.random() * w.height488	:lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end489	:lua print("There are " .. n .. " windows")490<491 492==============================================================================4939. luaeval() Vim function				*lua-luaeval* *lua-eval*494 495The (dual) equivalent of "vim.eval" for passing Lua values to Vim is496"luaeval".  "luaeval" takes an expression string and an optional argument and497returns the result of the expression.  It is semantically equivalent in Lua498to:499>500	local chunkheader = "local _A = select(1, ...) return "501	function luaeval (expstr, arg)502	    local chunk = assert(loadstring(chunkheader .. expstr, "luaeval"))503	    return chunk(arg) -- return typval504	end505<506Note that "_A" receives the argument to "luaeval".  Lua numbers, strings, and507list, dict, blob, and funcref userdata are converted to their Vim respective508types, while Lua booleans are converted to numbers.  An error is thrown if509conversion of any of the remaining Lua types, including userdata other than510lists, dicts, blobs, and funcrefs, is attempted.511 512Examples: >513 514	:echo luaeval('math.pi')515	:lua a = vim.list():add('newlist')516	:let a = luaeval('a')517	:echo a[0] " 'newlist'518	:function Rand(x,y) " random uniform between x and y519	:  return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y})520	:  endfunction521	:echo Rand(1,10)522 523 524==============================================================================52510. Dynamic loading				    *lua-dynamic*526 527On MS-Windows and Unix the Lua library can be loaded dynamically.  The528|:version| output then includes |+lua/dyn|.529 530This means that Vim will search for the Lua DLL or shared library file only531when needed.  When you don't use the Lua interface you don't need it, thus532you can use Vim without this file.533 534 535MS-Windows ~536 537To use the Lua interface the Lua DLL must be in your search path.  In a538console window type "path" to see what directories are used.  The 'luadll'539option can be also used to specify the Lua DLL.  The version of the DLL must540match the Lua version Vim was compiled with.541 542 543Unix ~544 545The 'luadll' option can be used to specify the Lua shared library file instead546of DYNAMIC_LUA_DLL file what was specified at compile time.  The version of547the shared library must match the Lua version Vim was compiled with.548 549 550==============================================================================551 vim:tw=78:ts=8:noet:ft=help:norl:552