| *if_lua.txt* For Vim version 7.3. 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. Buffer userdata |lua-buffer| |
| 6. Window userdata |lua-window| |
| 7. 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() Returns an empty list (see |List|). |
| |
| vim.dict() Returns an empty dictionary (see |Dictionary|). |
| |
| 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", "buffer", or "window" if {arg} is a |
| list, dictionary, 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. 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 |
| < |
| |
| ============================================================================== |
| 6. 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") |
| < |
| |
| ============================================================================== |
| 7. 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". 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: |