Mercurial > vim

comparison runtime/doc/if_lua.txt @ 3450:b067b8b81be9 v7.3.490

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated for version 7.3.490 Problem: Member confusion in Lua interface. Solution: Fix it. Add luaeval(). (Taro Muraoka, Luis Carvalho)
author Bram Moolenaar <bram@vim.org>
date Thu, 05 Apr 2012 16:54:08 +0200
parents ee53a39d5896
children 161d01cbb165
comparison
equal deleted inserted replaced
3449:3107917c6aed 3450:b067b8b81be9
1 *if_lua.txt* For Vim version 7.3. Last change: 2010 Jul 22 1 *if_lua.txt* For Vim version 7.3. Last change: 2012 Jan 16
2 2
3 3
4 VIM REFERENCE MANUAL by Luis Carvalho 4 VIM REFERENCE MANUAL by Luis Carvalho
5 5
6 6
7 The Lua Interface to Vim *lua* *Lua* 7 The Lua Interface to Vim *lua* *Lua*
8 8
9 1. Commands |lua-commands| 9 1. Commands |lua-commands|
10 2. The vim module |lua-vim| 10 2. The vim module |lua-vim|
11 3. Buffer userdata |lua-buffer| 11 3. List userdata |lua-list|
12 4. Window userdata |lua-window| 12 4. Dict userdata |lua-dict|
13 5. Buffer userdata |lua-buffer|
14 6. Window userdata |lua-window|
15 7. The luaeval function |lua-luaeval|
13 16
14 {Vi does not have any of these commands} 17 {Vi does not have any of these commands}
15 18
16 The Lua interface is available only when Vim was compiled with the 19 The Lua interface is available only when Vim was compiled with the
17 |+lua| feature. 20 |+lua| feature.
86 < 89 <
87 90
88 All these commands execute a Lua chunk from either the command line (:lua and 91 All 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 92 :luado) or a file (:luafile) with the given line [range]. Similarly to the Lua
90 interpreter, each chunk has its own scope and so only global variables are 93 interpreter, each chunk has its own scope and so only global variables are
91 shared between command calls. Lua default libraries "table", "string", "math", 94 shared between command calls. All Lua default libraries are available. In
92 and "package" are available, "io" and "debug" are not, and "os" is restricted 95 addition, Lua "print" function has its output redirected to the Vim message
93 to functions "date", "clock", "time", "difftime", and "getenv". In addition, 96 area, with arguments separated by a white space instead of a tab.
94 Lua "print" function has its output redirected to the Vim message area, with
95 arguments separated by a white space instead of a tab.
96 97
97 Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim 98 Lua uses the "vim" module (see |lua-vim|) to issue commands to Vim
98 and manage buffers (|lua-buffer|) and windows (|lua-window|). However, 99 and manage buffers (|lua-buffer|) and windows (|lua-window|). However,
99 procedures that alter buffer content, open new buffers, and change cursor 100 procedures that alter buffer content, open new buffers, and change cursor
100 position are restricted when the command is executed in the |sandbox|. 101 position are restricted when the command is executed in the |sandbox|.
106 Lua interfaces Vim through the "vim" module. The first and last line of the 107 Lua interfaces Vim through the "vim" module. The first and last line of the
107 input range are stored in "vim.firstline" and "vim.lastline" respectively. The 108 input range are stored in "vim.firstline" and "vim.lastline" respectively. The
108 module also includes routines for buffer, window, and current line queries, 109 module also includes routines for buffer, window, and current line queries,
109 Vim evaluation and command execution, and others. 110 Vim evaluation and command execution, and others.
110 111
111 vim.isbuffer(value) Returns 'true' (boolean, not string) if 112 vim.list() Returns an empty list (see |List|).
112 "value" is a buffer userdata and 'false' 113
113 otherwise (see |lua-buffer|). 114 vim.dict() Returns an empty dictionary (see |Dictionary|).
114 115
115 vim.buffer([arg]) If "arg" is a number, returns buffer with 116 vim.buffer([arg]) If "arg" is a number, returns buffer with
116 number "arg" in the buffer list or, if "arg" 117 number "arg" in the buffer list or, if "arg"
117 is a string, returns buffer whose full or short 118 is a string, returns buffer whose full or short
118 name is "arg". In both cases, returns 'nil' 119 name is "arg". In both cases, returns 'nil'
119 (nil value, not string) if the buffer is not 120 (nil value, not string) if the buffer is not
120 found. Otherwise, if "toboolean(arg)" is 121 found. Otherwise, if "toboolean(arg)" is
121 'true' returns the first buffer in the buffer 122 'true' returns the first buffer in the buffer
122 list or else the current buffer. 123 list or else the current buffer.
123 124
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 125 vim.window([arg]) If "arg" is a number, returns window with
129 number "arg" or 'nil' (nil value, not string) 126 number "arg" or 'nil' (nil value, not string)
130 if not found. Otherwise, if "toboolean(arg)" 127 if not found. Otherwise, if "toboolean(arg)"
131 is 'true' returns the first window or else the 128 is 'true' returns the first window or else the
132 current window. 129 current window.
133 130
131 vim.type({arg}) Returns the type of {arg}. It is equivalent to
132 Lua's "type" function, but returns "list",
133 "dict", "buffer", or "window" if {arg} is a
134 list, dictionary, buffer, or window,
135 respectively. Examples: >
136 :lua l = vim.list()
137 :lua print(type(l), vim.type(l))
138 :" userdata list
139 <
134 vim.command({cmd}) Executes the vim (ex-mode) command {cmd}. 140 vim.command({cmd}) Executes the vim (ex-mode) command {cmd}.
135 Examples: > 141 Examples: >
136 :lua vim.command"set tw=60" 142 :lua vim.command"set tw=60"
137 :lua vim.command"normal ddp" 143 :lua vim.command"normal ddp"
138 < 144 <
139 vim.eval({expr}) Evaluates expression {expr} (see |expression|), 145 vim.eval({expr}) Evaluates expression {expr} (see |expression|),
140 converts the result to Lua, and returns it. 146 converts the result to Lua, and returns it.
141 Vim strings and numbers are directly converted 147 Vim strings and numbers are directly converted
142 to Lua strings and numbers respectively. Vim 148 to Lua strings and numbers respectively. Vim
143 lists and dictionaries are converted to Lua 149 lists and dictionaries are converted to Lua
144 tables (lists become integer-keyed tables). 150 userdata (see |lua-list| and |lua-dict|).
145 Examples: > 151 Examples: >
146 :lua tw = vim.eval"&tw" 152 :lua tw = vim.eval"&tw"
147 :lua print(vim.eval"{'a': 'one'}".a) 153 :lua print(vim.eval"{'a': 'one'}".a)
148 < 154 <
149 vim.line() Returns the current line (without the trailing 155 vim.line() Returns the current line (without the trailing
155 returns it. Note that the buffer is not set as 161 returns it. Note that the buffer is not set as
156 current. 162 current.
157 163
158 164
159 ============================================================================== 165 ==============================================================================
160 3. Buffer userdata *lua-buffer* 166 3. List userdata *lua-list*
167
168 List userdata represent vim lists, and the interface tries to follow closely
169 Vim's syntax for lists. Since lists are objects, changes in list references in
170 Lua are reflected in Vim and vice-versa. A list "l" has the following
171 properties and methods:
172
173 Properties
174 ----------
175 o "#l" is the number of items in list "l", equivalent to "len(l)"
176 in Vim.
177 o "l[k]" returns the k-th item in "l"; "l" is zero-indexed, as in Vim.
178 To modify the k-th item, simply do "l[k] = newitem"; in
179 particular, "l[k] = nil" removes the k-th item from "l".
180 o "l()" returns an iterator for "l".
181
182 Methods
183 -------
184 o "l:add(item)" appends "item" to the end of "l".
185 o "l:insert(item[, pos])" inserts "item" at (optional)
186 position "pos" in the list. The default value for "pos" is 0.
187
188 Examples:
189 >
190 :let l = [1, 'item']
191 :lua l = vim.eval('l') -- same 'l'
192 :lua l:add(vim.list())
193 :lua l[0] = math.pi
194 :echo l[0] " 3.141593
195 :lua l[0] = nil -- remove first item
196 :lua l:insert(true, 1)
197 :lua print(l, #l, l[0], l[1], l[-1])
198 :lua for item in l() do print(item) end
199 <
200
201 ==============================================================================
202 4. Dict userdata *lua-dict*
203
204 Similarly to list userdata, dict userdata represent vim dictionaries; since
205 dictionaries are also objects, references are kept between Lua and Vim. A dict
206 "d" has the following properties:
207
208 Properties
209 ----------
210 o "#d" is the number of items in dict "d", equivalent to "len(d)"
211 in Vim.
212 o "d.key" or "d['key']" returns the value at entry "key" in "d".
213 To modify the entry at this key, simply do "d.key = newvalue"; in
214 particular, "d.key = nil" removes the entry from "d".
215 o "d()" returns an iterator for "d" and is equivalent to "items(d)" in
216 Vim.
217
218 Examples:
219 >
220 :let d = {'n':10}
221 :lua d = vim.eval('d') -- same 'd'
222 :lua print(d, d.n, #d)
223 :let d.self = d
224 :lua for k, v in d() do print(d, k, v) end
225 :lua d.x = math.pi
226 :lua d.self = nil -- remove entry
227 :echo d
228 <
229
230 ==============================================================================
231 5. Buffer userdata *lua-buffer*
161 232
162 Buffer userdata represent vim buffers. A buffer userdata "b" has the following 233 Buffer userdata represent vim buffers. A buffer userdata "b" has the following
163 properties and methods: 234 properties and methods:
164 235
165 Properties 236 Properties
207 EOF 278 EOF
208 endfunction 279 endfunction
209 < 280 <
210 281
211 ============================================================================== 282 ==============================================================================
212 4. Window userdata *lua-window* 283 6. Window userdata *lua-window*
213 284
214 Window objects represent vim windows. A window userdata "w" has the following 285 Window objects represent vim windows. A window userdata "w" has the following
215 properties and methods: 286 properties and methods:
216 287
217 Properties 288 Properties
239 :lua n,w = 0,vim.window(true) while w~=nil do n,w = n + 1,w:next() end 310 :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") 311 :lua print("There are " .. n .. " windows")
241 < 312 <
242 313
243 ============================================================================== 314 ==============================================================================
244 vim:tw=78:ts=8:ft=help:norl: 315 7. The luaeval function *lua-luaeval*
316
317 The (dual) equivalent of "vim.eval" for passing Lua values to Vim is
318 "luaeval". "luaeval" takes an expression string and an optional argument and
319 returns the result of the expression. It is semantically equivalent in Lua to:
320 >
321 local chunkheader = "local _A = select(1, ...) return "
322 function luaeval (expstr, arg)
323 local chunk = assert(loadstring(chunkheader .. expstr, "luaeval"))
324 return chunk(arg) -- return typval
325 end
326 <
327 Note that "_A" receives the argument to "luaeval". Examples: >
328
329 :echo luaeval('math.pi')
330 :lua a = vim.list():add('newlist')
331 :let a = luaeval('a')
332 :echo a[0] " 'newlist'
333 :function Rand(x,y) " random uniform between x and y
334 : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y})
335 : endfunction
336 :echo Rand(1,10)
337
338
339 ==============================================================================
340 vim:tw=78:ts=8:noet:ft=help:norl: