diff options
Diffstat (limited to 'runtime/doc/if_lua.txt')
| -rw-r--r-- | runtime/doc/if_lua.txt | 550 |
1 files changed, 550 insertions, 0 deletions
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt new file mode 100644 index 0000000..63ee91a --- /dev/null +++ b/runtime/doc/if_lua.txt @@ -0,0 +1,550 @@ +*if_lua.txt* For Vim version 9.0. 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: |