diff options
Diffstat (limited to 'vim73/doc/if_lua.txt')
| -rw-r--r-- | vim73/doc/if_lua.txt | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/vim73/doc/if_lua.txt b/vim73/doc/if_lua.txt new file mode 100644 index 0000000..6514822 --- /dev/null +++ b/vim73/doc/if_lua.txt @@ -0,0 +1,244 @@ +*if_lua.txt* For Vim version 7.3. Last change: 2010 Jul 22 + + + VIM REFERENCE MANUAL by Luis Carvalho + + +The Lua Interface to Vim *lua* *Lua* + +1. Commands |lua-commands| +2. The vim module |lua-vim| +3. Buffer userdata |lua-buffer| +4. Window userdata |lua-window| + +{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) {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>. 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. Lua default libraries "table", "string", "math", +and "package" are available, "io" and "debug" are not, and "os" is restricted +to functions "date", "clock", "time", "difftime", and "getenv". 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.isbuffer(value) Returns 'true' (boolean, not string) if + "value" is a buffer userdata and 'false' + otherwise (see |lua-buffer|). + + 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.iswindow(value) Returns 'true' (boolean, not string) if + "value" is a window userdata and + 'false' otherwise (see |lua-window|). + + 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.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 + tables (lists become integer-keyed tables). + 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. 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 +< + +============================================================================== +4. 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") +< + +============================================================================== + vim:tw=78:ts=8:ft=help:norl: |