diff options
Diffstat (limited to 'runtime/doc/if_lua.txt')
| -rw-r--r-- | runtime/doc/if_lua.txt | 403 |
1 files changed, 0 insertions, 403 deletions
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt deleted file mode 100644 index 2b322ddbae..0000000000 --- a/runtime/doc/if_lua.txt +++ /dev/null @@ -1,403 +0,0 @@ -*if_lua.txt* For Vim version 7.4. Last change: 2013 Sep 04 - - - 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". NOT IMPLEMENTED YET - - 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: |