1*if_lua.txt* For Vim version 7.3. Last change: 2010 Jul 22 2 3 4 VIM REFERENCE MANUAL by Luis Carvalho 5 6 7The Lua Interface to Vim *lua* *Lua* 8 91. Commands |lua-commands| 102. The vim module |lua-vim| 113. Buffer userdata |lua-buffer| 124. Window userdata |lua-window| 13 14{Vi does not have any of these commands} 15 16The Lua interface is available only when Vim was compiled with the 17|+lua| feature. 18 19============================================================================== 201. Commands *lua-commands* 21 22 *:lua* 23:[range]lua {chunk} 24 Execute Lua chunk {chunk}. {not in Vi} 25 26Examples: 27> 28 :lua print("Hello, Vim!") 29 :lua local curbuf = vim.buffer() curbuf[7] = "line #7" 30< 31 32:[range]lua << {endmarker} 33{script} 34{endmarker} 35 Execute Lua script {script}. {not in Vi} 36 Note: This command doesn't work when the Lua 37 feature wasn't compiled in. To avoid errors, see 38 |script-here|. 39 40{endmarker} must NOT be preceded by any white space. If {endmarker} is 41omitted from after the "<<", a dot '.' must be used after {script}, like 42for the |:append| and |:insert| commands. 43This form of the |:lua| command is mainly useful for including Lua code 44in Vim scripts. 45 46Example: 47> 48 function! CurrentLineInfo() 49 lua << EOF 50 local linenr = vim.window().line 51 local curline = vim.buffer()[linenr] 52 print(string.format("Current line [%d] has %d chars", 53 linenr, #curline)) 54 EOF 55 endfunction 56< 57 58 *:luado* 59:[range]luado {body} Execute Lua function "function (line) {body} end" for 60 each line in the [range], with the function argument 61 being set to the text of each line in turn, without a 62 trailing <EOL>. If the value returned by the function 63 is a string it becomes the text of the line in the 64 current turn. The default for [range] is the whole 65 file: "1,$". {not in Vi} 66 67Examples: 68> 69 :luado return string.format("%s\t%d", line:reverse(), #line) 70 71 :lua require"lpeg" 72 :lua -- balanced parenthesis grammar: 73 :lua bp = lpeg.P{ "(" * ((1 - lpeg.S"()") + lpeg.V(1))^0 * ")" } 74 :luado if bp:match(line) then return "-->\t" .. line end 75< 76 77 *:luafile* 78:[range]luafile {file} 79 Execute Lua script in {file}. {not in Vi} 80 The whole argument is used as a single file name. 81 82Examples: 83> 84 :luafile script.lua 85 :luafile % 86< 87 88All these commands execute a Lua chunk from either the command line (:lua and 89:luado) or a file (:luafile) with the given line [range]. Similarly to the Lua 90interpreter, each chunk has its own scope and so only global variables are 91shared between command calls. Lua default libraries "table", "string", "math", 92and "package" are available, "io" and "debug" are not, and "os" is restricted 93to functions "date", "clock", "time", "difftime", and "getenv". In addition, 94Lua "print" function has its output redirected to the Vim message area, with 95arguments separated by a white space instead of a tab. 96 97Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim 98and manage buffers (|lua-buffer|) and windows (|lua-window|). However, 99procedures that alter buffer content, open new buffers, and change cursor 100position are restricted when the command is executed in the |sandbox|. 101 102 103============================================================================== 1042. The vim module *lua-vim* 105 106Lua interfaces Vim through the "vim" module. The first and last line of the 107input range are stored in "vim.firstline" and "vim.lastline" respectively. The 108module also includes routines for buffer, window, and current line queries, 109Vim evaluation and command execution, and others. 110 111 vim.isbuffer(value) Returns 'true' (boolean, not string) if 112 "value" is a buffer userdata and 'false' 113 otherwise (see |lua-buffer|). 114 115 vim.buffer([arg]) If "arg" is a number, returns buffer with 116 number "arg" in the buffer list or, if "arg" 117 is a string, returns buffer whose full or short 118 name is "arg". In both cases, returns 'nil' 119 (nil value, not string) if the buffer is not 120 found. Otherwise, if "toboolean(arg)" is 121 'true' returns the first buffer in the buffer 122 list or else the current buffer. 123 124 vim.iswindow(value) Returns 'true' (boolean, not string) if 125 "value" is a window userdata and 126 'false' otherwise (see |lua-window|). 127 128 vim.window([arg]) If "arg" is a number, returns window with 129 number "arg" or 'nil' (nil value, not string) 130 if not found. Otherwise, if "toboolean(arg)" 131 is 'true' returns the first window or else the 132 current window. 133 134 vim.command({cmd}) Executes the vim (ex-mode) command {cmd}. 135 Examples: > 136 :lua vim.command"set tw=60" 137 :lua vim.command"normal ddp" 138< 139 vim.eval({expr}) Evaluates expression {expr} (see |expression|), 140 converts the result to Lua, and returns it. 141 Vim strings and numbers are directly converted 142 to Lua strings and numbers respectively. Vim 143 lists and dictionaries are converted to Lua 144 tables (lists become integer-keyed tables). 145 Examples: > 146 :lua tw = vim.eval"&tw" 147 :lua print(vim.eval"{'a': 'one'}".a) 148< 149 vim.line() Returns the current line (without the trailing 150 <EOL>), a Lua string. 151 152 vim.beep() Beeps. 153 154 vim.open({fname}) Opens a new buffer for file {fname} and 155 returns it. Note that the buffer is not set as 156 current. 157 158 159============================================================================== 1603. Buffer userdata *lua-buffer* 161 162Buffer userdata represent vim buffers. A buffer userdata "b" has the following 163properties and methods: 164 165Properties 166---------- 167 o "b()" sets "b" as the current buffer. 168 o "#b" is the number of lines in buffer "b". 169 o "b[k]" represents line number k: "b[k] = newline" replaces line k 170 with string "newline" and "b[k] = nil" deletes line k. 171 o "b.name" contains the short name of buffer "b" (read-only). 172 o "b.fname" contains the full name of buffer "b" (read-only). 173 o "b.number" contains the position of buffer "b" in the buffer list 174 (read-only). 175 176Methods 177------- 178 o "b:insert(newline[, pos])" inserts string "newline" at (optional) 179 position "pos" in the buffer. The default value for "pos" is 180 "#b + 1". If "pos == 0" then "newline" becomes the first line in 181 the buffer. 182 o "b:next()" returns the buffer next to "b" in the buffer list. 183 o "b:previous()" returns the buffer previous to "b" in the buffer 184 list. 185 o "b:isvalid()" returns 'true' (boolean) if buffer "b" corresponds to 186 a "real" (not freed from memory) Vim buffer. 187 188Examples: 189> 190 :lua b = vim.buffer() -- current buffer 191 :lua print(b.name, b.number) 192 :lua b[1] = "first line" 193 :lua b:insert("FIRST!", 0) 194 :lua b[1] = nil -- delete top line 195 :lua for i=1,3 do b:insert(math.random()) end 196 :3,4lua for i=vim.lastline,vim.firstline,-1 do b[i] = nil end 197 :lua vim.open"myfile"() -- open buffer and set it as current 198 199 function! ListBuffers() 200 lua << EOF 201 local b = vim.buffer(true) -- first buffer in list 202 while b ~= nil do 203 print(b.number, b.name, #b) 204 b = b:next() 205 end 206 vim.beep() 207 EOF 208 endfunction 209< 210 211============================================================================== 2124. Window userdata *lua-window* 213 214Window objects represent vim windows. A window userdata "w" has the following 215properties and methods: 216 217Properties 218---------- 219 o "w()" sets "w" as the current window. 220 o "w.buffer" contains the buffer of window "w" (read-only). 221 o "w.line" represents the cursor line position in window "w". 222 o "w.col" represents the cursor column position in window "w". 223 o "w.width" represents the width of window "w". 224 o "w.height" represents the height of window "w". 225 226Methods 227------- 228 o "w:next()" returns the window next to "w". 229 o "w:previous()" returns the window previous to "w". 230 o "w:isvalid()" returns 'true' (boolean) if window "w" corresponds to 231 a "real" (not freed from memory) Vim window. 232 233Examples: 234> 235 :lua w = vim.window() -- current window 236 :lua print(w.buffer.name, w.line, w.col) 237 :lua w.width = w.width + math.random(10) 238 :lua w.height = 2 * math.random() * w.height 239 :lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end 240 :lua print("There are " .. n .. " windows") 241< 242 243============================================================================== 244 vim:tw=78:ts=8:ft=help:norl: 245